notebooks/introducing_functions.ipynb

{
 "metadata": {
  "name": "introducing_functions"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Introducing Functions\n",
      "===\n",
      "One of the core principles of any programming language is, \"Don't Repeat Yourself\". If you have an action that should occur many times, you can define that action once and then call that code whenever you need to carry out that action.\n",
      "\n",
      "We are already repeating ourselves in our code, so this is a good time to introduce simple functions. Functions mean less work for us as programmers, and effective use of functions results in code that is less error-prone."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "[Previous: Lists and Tuples](http://nbviewer.ipython.org/urls/raw.github.com/ehmatthes/intro_programming/master/notebooks/lists_tuples.ipynb) | \n",
      "[Home](http://nbviewer.ipython.org/urls/raw.github.com/ehmatthes/intro_programming/master/notebooks/index.ipynb) |\n",
      "[Next: If Statements](http://nbviewer.ipython.org/urls/raw.github.com/ehmatthes/intro_programming/master/notebooks/if_statements.ipynb)"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Contents\n",
      "===\n",
      "- [What are functions?](#what)\n",
      "    - [General Syntax](#general_syntax)\n",
      "- [Examples](#examples)\n",
      "    - [Returning a Value](#return_value)\n",
      "    - [Exercises](#exercises)\n",
      "- [Challenges](#challenges)"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<a name='what'></a>What are functions?\n",
      "===\n",
      "Functions are a set of actions that we group together, and give a name to. You have already used a number of functions from the core Python language, such as *string.title()* and *list.sort()*. We can define our own functions, which allows us to \"teach\" Python new behavior."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<a name='general_syntax'></a>General Syntax\n",
      "---\n",
      "A general function looks something like this:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# Let's define a function.\n",
      "def function_name(argument_1, argument_2):\n",
      "\t# Do whatever we want this function to do,\n",
      "\t#  using argument_1 and argument_2\n",
      "\n",
      "# Use function_name to call the function.\n",
      "function_name(value_1, value_2)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This code will not run, but it shows how functions are used in general.\n",
      "\n",
      "- **Defining a function**\n",
      "    - Give the keyword `def`, which tells Python that you are about to *define* a function.\n",
      "    - Give your function a name. A variable name tells you what kind of value the variable contains; a function name should tell you what the function does.\n",
      "    - Give names for each value the function needs in order to do its work.\n",
      "        - These are basically variable names, but they are only used in the function.\n",
      "        - They can be different names than what you use in the rest of your program.\n",
      "        - These are called the function's *arguments*.\n",
      "    - Make sure the function definition line ends with a colon.\n",
      "    - Inside the function, write whatever code you need to make the function do its work.\n",
      "- **Using your function**\n",
      "    - To *call* your function, write its name followed by parentheses.\n",
      "    - Inside the parentheses, give the values you want the function to work with.\n",
      "        - These can be variables such as `current_name` and `current_age`, or they can be actual values such as 'eric' and 5."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "[top](#)"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<a name='examples'></a>Basic Examples\n",
      "===\n",
      "For a simple first example, we will look at a program that compliments people. Let's look at the example, and then try to understand the code. First we will look at a version of this program as we would have written it earlier, with no functions."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "print(\"You are doing good work, Adriana!\")\n",
      "print(\"Thank you very much for your efforts on this project.\")\n",
      "\n",
      "print(\"\\nYou are doing good work, Billy!\")\n",
      "print(\"Thank you very much for your efforts on this project.\")\n",
      "\n",
      "print(\"\\nYou are doing good work, Caroline!\")\n",
      "print(\"Thank you very much for your efforts on this project.\")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "You are doing good work, Adriana!\n",
        "Thank you very much for your efforts on this project.\n",
        "\n",
        "You are doing good work, Billy!\n",
        "Thank you very much for your efforts on this project.\n",
        "\n",
        "You are doing good work, Caroline!\n",
        "Thank you very much for your efforts on this project.\n"
       ]
      }
     ],
     "prompt_number": 2
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Functions take repeated code, put it in one place, and then you call that code when you want to use it. Here's what the same program looks like with a function."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "def thank_you(name):\n",
      "    # This function prints a two-line personalized thank you message.\n",
      "    print(\"\\nYou are doing good work, %s!\" % name)\n",
      "    print(\"Thank you very much for your efforts on this project.\")\n",
      "    \n",
      "thank_you('Adriana')\n",
      "thank_you('Billy')\n",
      "thank_you('Caroline')"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "\n",
        "You are doing good work, Adriana!\n",
        "Thank you very much for your efforts on this project.\n",
        "\n",
        "You are doing good work, Billy!\n",
        "Thank you very much for your efforts on this project.\n",
        "\n",
        "You are doing good work, Caroline!\n",
        "Thank you very much for your efforts on this project.\n"
       ]
      }
     ],
     "prompt_number": 4
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "In our original code, each pair of print statements was run three times, and the only difference was the name of the person being thanked. When you see repetition like this, you can usually make your program more efficient by defining a function.\n",
      "\n",
      "The keyword *def* tells Python that we are about to define a function. We give our function a name, *thank\\_you()* in this case. A variable's name should tell us what kind of information it holds; a function's name should tell us what the variable does.  We then put parentheses. Inside these parenthese we create variable names for any variable the function will need to be given in order to do its job. In this case the function will need a name to include in the thank you message. The variable `name` will hold the value that is passed into the function *thank\\_you()*.\n",
      "\n",
      "To use a function we give the function's name, and then put any values the function needs in order to do its work. In this case we call the function three times, each time passing it a different name."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "### A common error\n",
      "A function must be defined before you use it in your program. For example, putting the function at the end of the program would not work."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "thank_you('Adriana')\n",
      "thank_you('Billy')\n",
      "thank_you('Caroline')\n",
      "\n",
      "def thank_you(name):\n",
      "    # This function prints a two-line personalized thank you message.\n",
      "    print(\"\\nYou are doing good work, %s!\" % name)\n",
      "    print(\"Thank you very much for your efforts on this project.\")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "ename": "NameError",
       "evalue": "name 'thank_you' is not defined",
       "output_type": "pyerr",
       "traceback": [
        "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m\n\u001b[1;31mNameError\u001b[0m                                 Traceback (most recent call last)",
        "\u001b[1;32m<ipython-input-1-a1b6b8373f44>\u001b[0m in \u001b[0;36m<module>\u001b[1;34m()\u001b[0m\n\u001b[1;32m----> 1\u001b[1;33m \u001b[0mthank_you\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;34m'Adriana'\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0m\u001b[0;32m      2\u001b[0m \u001b[0mthank_you\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;34m'Billy'\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m      3\u001b[0m \u001b[0mthank_you\u001b[0m\u001b[1;33m(\u001b[0m\u001b[1;34m'Caroline'\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m      4\u001b[0m \u001b[1;33m\u001b[0m\u001b[0m\n\u001b[0;32m      5\u001b[0m \u001b[1;32mdef\u001b[0m \u001b[0mthank_you\u001b[0m\u001b[1;33m(\u001b[0m\u001b[0mname\u001b[0m\u001b[1;33m)\u001b[0m\u001b[1;33m:\u001b[0m\u001b[1;33m\u001b[0m\u001b[0m\n",
        "\u001b[1;31mNameError\u001b[0m: name 'thank_you' is not defined"
       ]
      }
     ],
     "prompt_number": 1
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "On the first line we ask Python to run the function *thank\\_you()*, but Python does not yet know how to do this function. We define our functions at the beginning of our programs, and then we can use them when we need to."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "A second example\n",
      "---\n",
      "When we introduced the different methods for [sorting a list](http://nbviewer.ipython.org/urls/raw.github.com/ehmatthes/intro_programming/master/notebooks/lists_tuples.ipynb#sorting_list), our code got very repetitive. It takes two lines of code to print a list using a for loop, so these two lines are repeated whenever you want to print out the contents of a list. This is the perfect opportunity to use a function, so let's see how the code looks with a function.\n",
      "\n",
      "First, let's see the code we had without a function:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "students = ['bernice', 'aaron', 'cody']\n",
      "\n",
      "# Put students in alphabetical order.\n",
      "students.sort()\n",
      "\n",
      "# Display the list in its current order.\n",
      "print(\"Our students are currently in alphabetical order.\")\n",
      "for student in students:\n",
      "    print(student.title())\n",
      "\n",
      "# Put students in reverse alphabetical order.\n",
      "students.sort(reverse=True)\n",
      "\n",
      "# Display the list in its current order.\n",
      "print(\"\\nOur students are now in reverse alphabetical order.\")\n",
      "for student in students:\n",
      "    print(student.title())"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Our students are currently in alphabetical order.\n",
        "Aaron\n",
        "Bernice\n",
        "Cody\n",
        "\n",
        "Our students are now in reverse alphabetical order.\n",
        "Cody\n",
        "Bernice\n",
        "Aaron\n"
       ]
      }
     ],
     "prompt_number": 3
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Here's what the same code looks like, using a function to print out the list:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "###highlight=[2,3,4,5,6,12,16]\n",
      "def show_students(students, message):\n",
      "    # Print out a message, and then the list of students\n",
      "    print(message)\n",
      "    for student in students:\n",
      "        print(student.title())\n",
      "\n",
      "students = ['bernice', 'aaron', 'cody']\n",
      "\n",
      "# Put students in alphabetical order.\n",
      "students.sort()\n",
      "show_students(students, \"Our students are currently in alphabetical order.\")\n",
      "\n",
      "#Put students in reverse alphabetical order.\n",
      "students.sort(reverse=True)\n",
      "show_students(students, \"\\nOur students are now in reverse alphabetical order.\")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Our students are currently in alphabetical order.\n",
        "Aaron\n",
        "Bernice\n",
        "Cody\n",
        "\n",
        "Our students are now in reverse alphabetical order.\n",
        "Cody\n",
        "Bernice\n",
        "Aaron\n"
       ]
      }
     ],
     "prompt_number": 9
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This is much cleaner code. We have an action we want to take, which is to show the students in our list along with a message. We give this action a name, *show\\_students()*. \n",
      "\n",
      "This function needs two pieces of information to do its work, the list of students and a message to display. Inside the function, the code for printing the message and looping through the list is exactly as it was in the non-function code.\n",
      "\n",
      "Now the rest of our program is cleaner, because it gets to focus on the things we are changing in the list, rather than having code for printing the list. We define the list, then we sort it and call our function to print the list. We sort it again, and then call the printing function a second time, with a different message. This is much more readable code.\n",
      "\n",
      "### Advantages of using functions\n",
      "You might be able to see some advantages of using functions, through this example:\n",
      "\n",
      "- We write a set of instructions once. We save some work in this simple example, and we save even more work in larger programs.\n",
      "- When our function works, we don't have to worry about that code anymore. Every time you repeat code in your program, you introduce an opportunity to make a mistake. Writing a function means there is one place to fix mistakes, and when those bugs are fixed, we can be confident that this function will continue to work correctly.\n",
      "- We can modify our function's behavior, and that change takes effect every time the function is called. This is much better than deciding we need some new behavior, and then having to change code in many different places in our program."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "For a quick example, let's say we decide our printed output would look better with some form of a bulleted list. Without functions, we'd have to change each print statement. With a function, we change just the print statement in the function:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "def show_students(students, message):\n",
      "    # Print out a message, and then the list of students\n",
      "    print(message)\n",
      "    for student in students:\n",
      "        print(\"- \" + student.title())\n",
      "\n",
      "students = ['bernice', 'aaron', 'cody']\n",
      "\n",
      "# Put students in alphabetical order.\n",
      "students.sort()\n",
      "show_students(students, \"Our students are currently in alphabetical order.\")\n",
      "\n",
      "#Put students in reverse alphabetical order.\n",
      "students.sort(reverse=True)\n",
      "show_students(students, \"\\nOur students are now in reverse alphabetical order.\")"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Our students are currently in alphabetical order.\n",
        "- Aaron\n",
        "- Bernice\n",
        "- Cody\n",
        "\n",
        "Our students are now in reverse alphabetical order.\n",
        "- Cody\n",
        "- Bernice\n",
        "- Aaron\n"
       ]
      }
     ],
     "prompt_number": 10
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "You can think of functions as a way to \"teach\" Python some new behavior. In this case, we taught Python how to create a list of students using hyphens; now we can tell Python to do this with our students whenever we want to."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<a name='return_value'></a>Returning a Value\n",
      "---\n",
      "Each function you create can return a value. This can be in addition to the primary work the function does, or it can be the function's main job. The following function takes in a number, and returns the corresponding word for that number:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "def get_number_word(number):\n",
      "    # Takes in a numerical value, and returns\n",
      "    #  the word corresponding to that number.\n",
      "    if number == 1:\n",
      "        return 'one'\n",
      "    elif number == 2:\n",
      "        return 'two'\n",
      "    elif number == 3:\n",
      "        return 'three'\n",
      "    # ...\n",
      "    \n",
      "# Let's try out our function.\n",
      "for current_number in range(0,4):\n",
      "    number_word = get_number_word(current_number)\n",
      "    print(current_number, number_word)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "0 None\n",
        "1 one\n",
        "2 two\n",
        "3 three\n"
       ]
      }
     ],
     "prompt_number": 3
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "It's helpful sometimes to see programs that don't quite work as they are supposed to, and then see how those programs can be improved. In this case, there are no Python errors; all of the code has proper Python syntax. But there is a logical error, in the first line of the output.\n",
      "\n",
      "We want to either not include 0 in the range we send to the function, or have the function return something other than `None` when it receives a value that it doesn't know. Let's teach our function the word 'zero', but let's also add an `else` clause that returns a more informative message for numbers that are not in the if-chain."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "###highlight=[13,14,17]\n",
      "def get_number_word(number):\n",
      "    # Takes in a numerical value, and returns\n",
      "    #  the word corresponding to that number.\n",
      "    if number == 0:\n",
      "        return 'zero'\n",
      "    elif number == 1:\n",
      "        return 'one'\n",
      "    elif number == 2:\n",
      "        return 'two'\n",
      "    elif number == 3:\n",
      "        return 'three'\n",
      "    else:\n",
      "        return \"I'm sorry, I don't know that number.\"\n",
      "    \n",
      "# Let's try out our function.\n",
      "for current_number in range(0,6):\n",
      "    number_word = get_number_word(current_number)\n",
      "    print(current_number, number_word)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "0 zero\n",
        "1 one\n",
        "2 two\n",
        "3 three\n",
        "4 I'm sorry, I don't know that number.\n",
        "5 I'm sorry, I don't know that number.\n"
       ]
      }
     ],
     "prompt_number": 5
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "If you use a return statement in one of your functions, keep in mind that the function stops executing as soon as it hits a return statement. For example, we can add a line to the *get\\_number\\_word()* function that will never execute, because it comes after the function has returned a value:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "###highlight=[16,17,18]\n",
      "def get_number_word(number):\n",
      "    # Takes in a numerical value, and returns\n",
      "    #  the word corresponding to that number.\n",
      "    if number == 0:\n",
      "        return 'zero'\n",
      "    elif number == 1:\n",
      "        return 'one'\n",
      "    elif number == 2:\n",
      "        return 'two'\n",
      "    elif number == 3:\n",
      "        return 'three'\n",
      "    else:\n",
      "        return \"I'm sorry, I don't know that number.\"\n",
      "    \n",
      "    # This line will never execute, because the function has already\n",
      "    #  returned a value and stopped executing.\n",
      "    print(\"This message will never be printed.\")\n",
      "    \n",
      "# Let's try out our function.\n",
      "for current_number in range(0,6):\n",
      "    number_word = get_number_word(current_number)\n",
      "    print(current_number, number_word)"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "0 zero\n",
        "1 one\n",
        "2 two\n",
        "3 three\n",
        "4 I'm sorry, I don't know that number.\n",
        "5 I'm sorry, I don't know that number.\n"
       ]
      }
     ],
     "prompt_number": 7
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "More Later\n",
      "---\n",
      "There is much more to learn about functions, but we will get to those details later. For now, feel free to use functions whenever you find yourself writing the same code several times in a program. Some of the things you will learn when we focus on functions:\n",
      "\n",
      "- How to give the arguments in your function default values.\n",
      "- How to let your functions accept different numbers of arguments."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "[top](#)"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<a name='exercises'></a>Exercises\n",
      "---\n",
      "#### Greeter\n",
      "- Write a function that takes in a person's name, and prints out a greeting.\n",
      "    - The greeting must be at least three lines, and the person's name must be in each line.\n",
      "- Use your function to greet at least three different people.\n",
      "- **Bonus:** Store your three people in a list, and call your function from a `for` loop.\n",
      "\n",
      "#### Full Names\n",
      "- Write a function that takes in a first name and a last name, and prints out a nicely formatted full name, in a sentence. Your sentence could be as simple as, \"Hello, *full\\_name*.\"\n",
      "- Call your function three times, with a different name each time.\n",
      "\n",
      "#### Addition Calculator\n",
      "- Write a function that takes in two numbers, and adds them together. Make your function print out a sentence showing the two numbers, and the result.\n",
      "- Call your function with three different sets of numbers.\n",
      "\n",
      "#### Return Calculator\n",
      "- Modify *Addition Calculator* so that your function returns the sum of the two numbers. The printing should happen outside of the function.\n",
      "\n",
      "#### List Exercises - Functions\n",
      "- Go back and solve each of the following exercises from the section on [Lists and Tuples](http://nbviewer.ipython.org/urls/raw.github.com/ehmatthes/intro_programming/master/notebooks/lists_tuples.ipynb), using functions to avoid repetetive code:\n",
      "    - [Ordered Working List](http://nbviewer.ipython.org/urls/raw.github.com/ehmatthes/intro_programming/master/notebooks/lists_tuples.ipynb#exercises_common_operations)\n",
      "    - [Ordered Numbers](http://nbviewer.ipython.org/urls/raw.github.com/ehmatthes/intro_programming/master/notebooks/lists_tuples.ipynb#exercises_common_operations)\n",
      "\n"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "[top](#)"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<a name='challenges'></a>Challenges\n",
      "---\n",
      "#### Lyrics\n",
      "- Many songs follow a familiar variation of the pattern of *verse*, *refrain*, *verse*, *refrain*. The verses are the parts of the song that tell a story - they are not repeated in the song. The refrain is the part of the song that is repeated throughout the song.\n",
      "- Find the lyrics to a [song you like](http://www.metrolyrics.com/dont-stop-believin-lyrics-journey.html) that follows this pattern. Write a program that prints out the lyrics to this song, using as few lines of Python code as possible. [hint](#hint_challenges_lyrics)"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "[top](#)"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "- - -\n",
      "[Previous: Lists and Tuples](http://nbviewer.ipython.org/urls/raw.github.com/ehmatthes/intro_programming/master/notebooks/lists_tuples.ipynb) | \n",
      "[Home](http://nbviewer.ipython.org/urls/raw.github.com/ehmatthes/intro_programming/master/notebooks/index.ipynb)"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Hints\n",
      "===\n",
      "These are placed at the bottom, so you can have a chance to solve exercises without seeing any hints.\n",
      "\n",
      "#### <a name='hints_lyrics'></a>Lyrics\n",
      "- Define a function that prints out the lyrics of the refrain. Use this function any time the refrain comes up in the song."
     ]
    }
   ],
   "metadata": {}
  }
 ]
}