.. Objectives
.. ----------

.. 8.1 LO: getting started with functions (3)

.. At the end of this tutorial, you will be able to 

.. 1. define function
.. #. define functions with arguments
.. #. learn about docstrings
.. #. learn about return values
..     can return multiple values
.. #. read code


.. Prerequisites
.. -------------

..   1. should have ``ipython`` installed. 
..   #. getting started with ``ipython``.

     
.. Author              : Anoop Jacob Thomas <anoop@fossee.in>
   Internal Reviewer   : 
   External Reviewer   :
   Checklist OK?       : <put date stamp here, if OK> [2010-10-05]


==============================
Getting started with functions
==============================

{{{ show welcome slide }}}

Hello and welcome to the tutorial, getting started with functions.

{{{ switch to next slide, outline slide }}}

In this tutorial we will learn about functions in python, how to
define functions, passing arguments to functions, docstrings, and
function return value.

{{{ switch to next slide, Function }}}

While writing code, we would like to reduce the number of lines of
code and using functions is a way of reusing the code.  A function is
a portion of code within a larger program that performs a specific
task and is relatively independent of the remaining code. Now let us
get more familiar with functions,

{{{ switch to next slide, f(x) a mathematical function }}}

Consider a mathematical function f(x) = x squared. Here x is a
variable and with different values of x the value of function will
change. When x is one f(1) will return the value 1 and f(2) will
return us the value 4. Let us now see how to define the function f(x)
in Python.

{{{ switch to next slide, define f(x) in Python }}}

In your Ipython interpreter type the following,
::

    def f(x):
    	return x*x

Let us see, if the function ``f``, we defined, works as we expect. 
::

    f(1)
    f(2)

Yes, it returned 1 and 2 respectively. 

Now, let us see what we did. The first line ``def f(x)`` is used to
define the name and the parameters to the function. ``def`` is a
keyword and ``f`` is the name of the function and ``x`` the parameter
of the function.  

The second line is the body of the function. Incidentally, this
function has a single line definition. Note that the body of the
function is indented, just like any other code block, in Python.

{{{ switch to next slide, problem statement 1 }}}

%% 1 %% Write a python function named cube which computes the cube of
   a given number n.

Pause here and try to solve the problem yourself.

{{{ switch to next slide, solution }}}

The problem can be solved as,
::

    def cube(n):
    	return n**3

Now let us see how to write functions without arguments.

{{{ switch to next slide, greet function }}}

Let us define a new function called ``greet`` which will print ``Hello
World``.
::

    def greet():
    	print "Hello World!"

Now try calling the function,
::

    greet()

Well that is a function which takes no arguments. Also note that it is
not mandatory for a function to return values. The function ``greet``
neither takes any argument nor returns any value.

Now let us see how to write functions with more than one argument.

{{{ switch to next slide, exercise 2 }}}

%% 2 %% Write a python function named ``avg`` which computes the
   average of ``a`` and ``b``.

Pause here and try to solve the problem yourself.

{{{ switch to next slide, solution 2 }}}

The problem can be solved as shown,
::

    def avg(a,b):
    	return (a + b)/2

Thus if we want a function to accept more arguments, we just list them
separated with a comma between the parenthesis after the function name
in the ``def`` line.

{{{ switch to next slide, docstring }}}

It is always a good practice to document the code that we write, and
for a function we define we should write an abstract of what the
function does, and that is called a doc-string. Let us modify the
function ``avg`` and add doc-string to it. Do the following,
::

    def avg(a,b):
        """ avg takes two numbers as input (a & b), and
	returns the average of a and b"""
	return (a+b)/2

Note that doc-strings are entered in the immediate line after the
function definition and put as a triple quoted string. And here as far
as the code functionality is concerned, we didn't do anything. We just
added an abstract of what the function does.

Now try this in the ipython interpreter.
::

    avg?

It displays the docstring as we gave it. Thus docstring is a good way
of documenting the function we write.

Try to do this,
::

    f?

It doesn't have a docstring associated with it. Also we cannot infer
anything from the function name, and thus we are forced to read the
code to understand anything about the function.

{{{ switch to next slide, exercise 3 }}}

%% 3 %% Add docstring to the function f.

Pause here and try to do it yourself.

{{{ switch to next slide, solution }}}

We need to define the function again to add docstring to the function
``f`` and we do it as,
::

    def f(x):
    	"""Accepts a number x as argument and,
	returns the square of the number x."""
	return x*x

{{{ switch to next slide, exercise 4 }}}

%% 4 %% Write a python function named ``circle`` which returns the
   area and perimeter of a circle given radius ``r``.

Pause here and try to solve the problem yourself.

{{{ switch to next slide, solution 4 }}}

The problem requires us to return two values instead of one which we
were doing till now. We can solve the problem as,
::

    def circle(r):
    	"""returns area and perimeter of a circle given radius r"""
	pi = 3.14
	area = pi * r * r
	perimeter = 2 * pi * r
	return area, perimeter

A python function can return any number of values. There is no
restriction for it.

Let us call the function ``circle`` as,
::

    a, p = circle(6)
    print a
    print p

Now we have done enough coding, let us do some code reading exercise,

{{{ switch to next slide, what }}}

What does the function ``what`` do?

.. def what( n ):
..     if n < 0: n = -n
..     while n > 0:
..         if n % 2 == 1:
..             return False
..         n /= 10
..     return True

Pause here and try to figure out what the function ``what`` does.

{{{ switch to next slide, even_digits }}}

.. def even_digits( n ):
..    """returns True if all the digits of number n is even
..    returns False if all the digits of number n is not even"""
..     if n < 0: n = -n
..     while n > 0:
..         if n % 2 == 1:
..             return False
..         n /= 10
..     return True

The function returns ``True`` if all the digits of the number ``n``
are even, otherwise it returns ``False``.

Now one more code reading exercise,

{{{ switch to next slide, what }}}

What does the function ``what`` do?

.. def what( n ):
..     i = 1
..     while i * i < n:
..         i += 1
..     return i * i == n, i

Pause here and try to figure out what the function ``what`` does.

{{{ switch to next slide, is_perfect_square }}}

.. def is_perfect_square( n ):
..     """returns True and square root of n, if n is a perfect square,
..     otherwise returns False and the square root of the 
..     next perfect square"""
..     i = 1
..     while i * i < n:
..         i += 1
..     return i * i == n, i


The function returns ``True`` and the square root of ``n`` if n is a
perfect square, otherwise it returns ``False`` and the square root of
the next perfect square.

This brings us to the end of this tutorial, in this tutorial we covered

{{{ switch to next slide, summary }}}

- Functions in Python
- Passing parameters to a function
- Returning values from a function

We also did few code reading exercises.

{{{ Show the "sponsored by FOSSEE" slide }}}

This tutorial was created as a part of FOSSEE project, NME ICT, MHRD India

Hope you have enjoyed and found it useful.
Thank you!