..  _simple-functions:

##############################
Getting started with Functions
##############################

What in the world is a ``function``. You already know. It is that ``sqrt``
thing you just worked out. It is that ``sin`` button on your calculator (no,
not that kind of sin, the other kind!).  Basically, this is what a function is:

A function is a box with some code in it. We do not want to worry about the
code, we just want the box to do something handy for us. Ideally, we do not
even need to write the code in the box, someone else did that for us.

We will use a lot of ``functions`` other people wrote in our Python programs.
For now, we just need to see how they are set up and how to use them.

********************
Layout of a function
********************

All functions have a basic structure. There is a ``function name`` we use to
refer to the function. There may be ``function parameters``, a fancy term for
pieces of data we need to give to the function before it can do its job. The
actual body of the function is where the real code lives. That code does the
work. Finally, there may be a return set of values handed back to us when the
function finishes its work. Not all functions return anything. More on that
later.

In Python, a function looks like this;

..  code-block:: text

    def mysqrt(number):
        guess = number / 2
        for guess_number in range(0,10):
            difference = number - guess * guess
            guess = (guess + number/guess)/2
        return guess

This is not a good function, but it does wrap up the logic we went over last time in a nice box.

But what does it all mean?

Function name
-------------

The ``def`` key-word marks the start of a ``function`` definition. The name of
the function follows immediately.

Function parameters
-------------------

After the name of the function, we must include an open parenthesis character.
Any ``parameters`` we want to give to the function will be listed after this
open parenthesis mark, and all will be separated by commas. When we are done
with the parameters, we include a close parenthesis character follows by a
colon.

Function body
-------------

The code for the function will be indented after the first line. All statements
so indented make up the body of our function. We can refer to the parameter as
we did with ``number`` in the above example. We know when we have hit the end
of the function because following code will not be indented.

Function return
---------------

Not all functions return anything, This one does, and we see what is returned
by that ``return`` statement.

All of this looks confusing, so I will use an analogy, created for game
programmers, to explain what is going on.

***************
Trolls in a box
***************

Pretend you have a really cool calculator but it is locked up in a box. The box
has slots on top, and another slot on the side. You have a bunch of cards on
top of the box. On the box is painted a name, something like ``sqrt``.

Setting up your parameters
--------------------------

You can pick up a card from the top of the box and write down some value next
to the name. When you are done, stick it in the top of the box

Now for the fun part
--------------------

Kick the box to wake up the troll.

(sound of furious activity followed by a new card sliding out of the box
through the slot on the side)

The Function return
-------------------

The answer to your problem is found on that final card.


What happened inside the box?
-----------------------------

When the troll woke up, he picked up the card. In invisible ink was the word
"number" followed by the value the fool who kicked the box wrote on the card.
The troll has a sheet with instructions on how to take that number thing and
punch keys on the calculator to figure out something. The deal is that if the
troll writes that something down on a new card and sticks it out the slot in
the side of the bx, he can go back to sleep. At least until another fool kicks
the box again.

Now, this sounds handy. If we have a bunch of trained trolls, each capable of
doing a different task, we can use then to solve complicated problems. Shoot,
we might have a super-troll with its own staff of sub-trolls that the
super-troll could use to solve really hard problems. Sounds kind of useful.

We will use simple functions in our next lab. For now, you get the idea (I hope!)