Learn how to create functions to reduce repeated code and increase usability!

Functions

We've been using `print` this whole time, but Lua comes with a lot more functions built in. For example, Lua has an entire collection of functions for using and manipulating strings. The **documentation** for these functions can be found on [Lua's Official Website](http://lua-users.org/wiki/StringLibraryTutorial). Additional examples for the string and other libraries can be found in the [user-maintained wiki](http://lua-users.org/wiki/TutorialDirectory)

This string function library contains functions like `string.upper` to convert a string to all upper cases.

```lua
string.upper("hello") -- returns HELLO
```

There is also an entire library of functions about math with useful functions like `math.random` that returns a random number, or  `math.min` to get the smaller of 2 numbers.

```lua
math.min(100, 250) -- returns 100
math.random() -- can return any decimal between 0 and 1
math.random(0, 100) -- can return any number between 0 and 100, including 0 or 100.
```

There are too many functions to go over in just this one lesson. More often than not, you won't be expected to memorize every single function that is available to you. It is much more useful to know how to find the function you need and learn how it is used. 

Let's practice this skill by looking at the Lua documentation for built-in functions.


Built-In Lua Functions

Now that we have a strong foundation for functions, let's practice writing a few more. For reference, here is the `getTravelTime` function we have been building:

```lua
function getTravelTime(mph, miles)
  travelTime = miles / mph
  return travelTime
end

print(getTravelTime(10, 60)) -- output: 6
```

For each function you write, test it out by printing the result as shown above with `print(functionName(args))`


Practice With Functions

Congratulations on working through functions! Let's review what we learned

```lua
function getTravelTime(mph, miles)
  travelTime = miles / mph
  return travelTime
end

getTravelTime(10, 60) – returns a value of 6
```

**Functions** are important for maximizing code-writing efficiency because they allow us to write code once and use it over and over. They have a few key components:
- `function` -  The keyword telling Lua that we want to make a function
- `getTravelTime` -  The name that describes what the function does, and is used when calling the function.
- `(mph, miles)` -  Function **parameters** are used to increase our function's flexibility. 
- `return travelTime` - The **return** keyword tells Lua what to send back to our function call. I.e. the function above returns the `travelTime` variable.
- `getTravelTime(...)` - A function can be **called** by using it's name followed by arguments. This runs the code inside the function.
- `(10,60)` - A function can have **arguments** that are values assigned to the parameters, like a value assigned to a variable.

Functions can be as simple or as complex as desired but are a key tool for writing efficient, readable, and well-organized code.


Review

In programming, as we start to write bigger and more complex programs, one thing we will start to notice is we will often have to repeat the same code in many different places.

Let’s imagine we are building an application that compares the travel time of driving, biking, and walking between two points. For any one of those modes of travel, the steps for calculating travel time might look like this: 

```pseudo
1. Establish the distance between the two points
2. Determine the travel speed
3. Calculate time = distance / speed
4. Display the time to the user
```

We will need to perform these four steps for each mode of transportation. In our program, we could rewrite the same procedure over and over (and over), but there’s a better way!

Instead, we can use **functions**. A function is a container for code that allows us to reuse that code throughout a program. Functions save us the trouble of having to re-write code that we've already written!
	
We already have practice using functions such as `print` and `type`! Whenever we want to print something to the screen we "call" the `print` function by adding parentheses and providing an input value:

```lua
print("This will be printed!") 
--Output: This will be printed!
```

`print` is an example of a function that Lua created for us so that we can print as many times as we want in our programs. No need to recreate it ourselves! 

In this lesson, we'll learn how to create our own functions as well as how to:

* Call functions
* Provide inputs to functions that change their behavior
* Return values from functions that we can use in our program
* And much more!

Let's get started!


Introduction to Functions

```lua
function getTravelTime()
  distance = 60
  mph = 10
  time = distance / mph
  print("It will take " .. time .. " hours to arrive.")
end
```

In our `getTravelTime` function we have been setting the `mph` to `10`. As a result, the function is limited to a biking speed and we can't compare travel times to walking or driving. What if we could provide the `mph` value when we call the function?

This is how `print` works. We call `print(____)` and fill in the blank with whatever text we want the function to print. 

We need to set up our function to take inputs (called **arguments**) that change how the function behaves. For our own functions to do this, they need **parameters**. Parameters are variables that are declared with the function but aren't assigned a value until they are called:

```lua
function getTravelTime(mph)
  distance = 60
  -- We've removed the variable declaration mph = 10
  time = distance / mph
  print("It will take " .. time .. " hours to arrive.")
end

getTravelTime(60) -- output: It will take 1 hours to arrive.
getTravelTime(30) -- output: It will take 2 hours to arrive.
```

Here, `mph` is our function's parameter and `60` and `30` are examples of **arguments**. Each time the function is called, the parameter `mph` is assigned the value of the argument provided. The result is a different output each time. 

We can also define a function to receive more than one argument, we just need to add more parameters with commas between them:

```lua
function getTravelTime(mph, distance)
  -- Now, both mph and distance are parameters
  time = distance / mph
  print("It will take " .. time .. " hours to travel " .. distance .. " miles.")
end

getTravelTime(60, 60) -- output: It will take 1 hours to travel 60 miles.
getTravelTime(30, 15) -- output: It will take 0.5 hours to travel 15 miles.
```

**Note:** If you were to call `getTravelTime(60)` then what would the function use for the missing `distanceInput`? By default, it will use the value `nil` which can cause errors down the road. 

Parameters and Arguments

While declaring a function is essential, it is only half of the battle. If we want the computer to run our function's code, the function must be **called**. 
To call a function, type the name it was defined with and add parentheses:

```lua
-- First we define the function
function getTravelTime()
  distance = 60
  mph = 10
  time = distance / speed
  print("It will take " .. time .. " hours to arrive.")
end

-- Then we can call it as many times as we want!
getTravelTime() -- output: "It will take 6 hours to arrive."
getTravelTime() -- output: "It will take 6 hours to arrive."
getTravelTime() -- output: "It will take 6 hours to arrive."
```

Remember that assigning a value to a variable is only useful if we reference that variable later. Similarly, declaring a function is only useful if we call that function later. Functions become more and more time-saving when we call them multiple times in our program.

You may notice that the output of the function is the same each time. We originally wanted to compare travel times between driving, biking, and walking! Don't worry — we'll fix that in a moment. For now, let's practice calling some functions.

**Note:** The function call must come *after* the function declaration.


Calling A Function

Let's stick with our travel time application.

```lua
distance = 60
mph = 10
time = distance / speed
print("It will take " .. time .. " hours to arrive.")
```

If we want to create a function for our code then we have to make a **function declaration**.

```lua
function getTravelTime()
  distance = 60
  mph = 10
  time = distance / speed
  print("It will take " .. time .. " hours to arrive.")
end
```

Most of the code is the same but we've added some things before and after. Let's look at what each part of this code is doing:
- `function` — This marks the start of our function.
- `getTravelTime` — The function's name. A function's name should describe what the function does to increase our code's readability.
- `()` — Parentheses are used to indicate any inputs. For now, there are none (indicated by the empty parentheses) but we'll add some later.
- The code of the function goes between the parentheses and `end` and is indented for improved readability.
- `end` — This marks the end of our function.

A function declaration can contain any code inside them. We can define variables, change them, and even call other functions (like `print()`) within our function declaration. By writing our code inside a function once, we enable us to reuse that code as many times as we want throughout our application.

Declaring Functions

One more important note about returns is that any code after a return statement will never be executed. Let's look at a modified version of our `getBoostedSpeed` function. In this example, if the input speed is less than `10`, we get a huge 5x boost! Otherwise, we get the normal 2x boost.

```lua
function getBoostedSpeed(baseSpeed)
  if (baseSpeed < 10)
    return baseSpeed * 5
  end
  return baseSpeed * 2 -- This runs if we didn't already return
end
```

We start our function with an `if` statement that we will only execute if our `baseSpeed` is less than `10`. Inside that `if` is a `return` statement. If our function returns, the rest of the function's code will be skipped. If you accidentally put some code after a `return` statement and it doesn't run, now you know why!

This feature of `return` can be useful for writing simplified functions. In this example, notice that we are effectively making an `if` and an `else` statement. We could have written:

```lua
function getBoostedSpeed(baseSpeed)
  if (baseSpeed < 10)
    return baseSpeed * 5
  else 
    return baseSpeed * 2
  end
end
```

You can choose to write your functions using either approach. Knowing how to use `return` is what's important at the end of the day!

Functions After Returns

As we have seen, our functions can receive outside information from the rest of the program. Our functions can also send information back. This is done through a **return**. 

Imagine we are making a racing game and our player has a `playerSpeed` variable that determines their car's speed. When the player drives over a speed boost, we can calculate the boosted speed using this function:

```lua
function getBoostedSpeed(baseSpeed)
  boostedSpeed = baseSpeed * 2
  return boostedSpeed
end
```

Notice the new keyword `return`! When used inside a function, the value after the `return` will be "spat out" of the function. This allows the _returned value_ to be used by the rest of the program. 

When calling a function that _returns_ a value we can assign the entire function call to a variable.

```lua
-- The starting player speed
playerSpeed = 10

-- The player drives over a speed boost
playerSpeed = getBoostedSpeed(playerSpeed)

print(playerSpeed)
-- Output: 20
```

We do something kind of tricky here too — we use the old value of `playerSpeed` as the input to get the new value! After the `getBoostedSpeed` function returns, we use the returned value to update `playerSpeed`.	
