Functions: Lesson

We now know how to define a function, so let's look closer at function return values. Calling a function to do some work and return a value is a common use of functions. It is important to understand how to define what type of value is returned and to ensure that it is returned.

Many of the C types we’ve seen so far can be used as a function return type like `int`, `double`, `char`, and even pointers. 
```c
int getSecretNumber() {
  int secretNumber = 7;
  return secretNumber;  
}
```
In the example above:
- The function has a return type `int`
- The variable `secretNumber`, of type `int`, is set to `7`
- The variable is returned using `return secretNumber`

The type of the value returned inside the function must match the type defined in the function signature. If there is a mismatch you will get a compilation error telling you of the mismatch.

Once the return statement is executed, the function gives control back to the function that called it and no further code within the function will be executed. For example:
```c
int getSecretNumber(){
  int secretNumber = 7;
  return secretNumber;  
  printf("Don’t tell anyone\n");
}
```
The `printf()` statement will not execute and `"Don’t tell anyone"` will not be displayed in the output terminal. 


Function Return Values

We’ve made great progress so far with functions! 

Up to this point when a function has received an argument, the function makes a copy of the argument's value and stores it in the parameter variable. Now any work that the function does on that parameter variable will not affect the original value passed in.

For example:
```c
#include <stdio.h>

void myFunc(int a){
  a = a + 2;
  printf("a inside myFunc(): %d\n", a);
}

int main(){
  int a = 10;
  myFunc(a);
  printf("a in main(): %d\n", a);
}

//OUTPUT:
// a inside myFunc(): 12;
// a in main(): 10;
```
This is great because we can safely alter the variable value inside the function while maintaining the original value outside.

What if we want to alter the variable inside the function? Instead of passing the actual variable as an argument, we can pass a pointer to the variable. Remember, a pointer is a variable that holds the memory address to another variable. The memory address tells you where the original variable is in memory. 

Before we pass a pointer to a function we need to make sure the parameter type matches the type of pointer we are passing. With a pointer as a parameter, the body of the function can directly alter the original value of the pointer that was passed:
```c
void myFunc(int* a){
  *a = *a+2;
  printf("a inside myFunc(): %d\n", *a);
}

int main(){
  int a = 10;
  int* aPointer = &a;
  myFunc(aPointer);
  printf("a in main(): %d\n", a);
}

//OUTPUT:
// a inside myFunc(): 12;
// a in main(): 12;
```
A benefit of using a pointer to a variable as opposed to the variable itself is that it saves memory as the function does not need to allocate more memory for complex data types like arrays. 

Functions with Pointers

As you continue to write more code there will be times when you’ll need to reuse a set of instructions. You might be tempted to reuse the code by copying and pasting it, but in times like this, a _function_ is a great tool to use.

A function is a group of instructions that is given a name to be used elsewhere in the code, often repeatedly. Functions can take in a set of inputs and produce some output.

![Cookie ingredients are input into a function, make-cookie. The output of the function is a cookie.](https://static-assets.codecademy.com/Courses/learn-c/functions/Function-Intro.svg)

In the photo above we use the idea of a function to make cookies. We collect a set of instructions (the recipe) under the name `makeCookie`. Baking a cookie requires a set of inputs (the ingredients). The instructions inside the function act on the input ingredients to produce the output (a cookie!). 

Functions are great because:
- You can write DRY (Don't Repeat Yourself) code.
- You can execute any number of instructions with a single line of code.
- Once a function exists, you only need to worry about the inputs and output and not about the instructions inside. 

In C, you have already worked with one function.  The `main()` function is the entry point to any C program and you will understand it better as you go through this lesson. 


Introduction

In the last exercise, we created a function `random1000()` that returned a random number between `1` and `1000`. What if we wanted the upper bound to be `10000` or `1000000`? We could define new functions like `getRandom10000()` or `getRandom1000000()`. There must be a better way.

Besides returning values, functions can customize their behavior based on the argument passed to them. This is done by defining parameters in the function signature.

Parameters are variable definitions that take place in between the parentheses of the function signature. They have a type and are given a name to be used inside and only inside the function body. Let's take a look!

```c
int addTwo(int number1, int number2) {
  int sum = number1 + number2;
  return sum;
}

int main() {
  int addedNumbers = addTwo(3, 6);
  // addedNumbers = 9
}
```
In the example above:
- The `addTwo()` function is defined with an integer return type
- The function takes two integer parameters, `number1` and `number2` to be used inside the function body
- The function adds the numbers together, assigns them to an integer, `sum` and returns `sum`
 
One thing to keep in mind is if the parameter type and the argument passed to a function do not match, a warning or an error will occur when we run the code.
```c
#include <stdio.h>

void sayIt(int number) {
  printf("%d\n", number);
}

int main(void) {
  char* string = "Hi!";
  sayIt(string);
}
```
The code above will produce a warning that the `sayIt` function argument type, `char*` and the parameter type, `int` are not the same. This will result in unwanted behavior.

The last thing to note about parameters is if a function does not have any parameters you should put `void` in between the parentheses. Leaving them empty will usually be OK, but it is best practice to use `void`.

Function Parameters

We’ve seen how C comes with many handy libraries full of functions for us to use. Now let's learn how to make our own! To begin, we need a function signature.

The function signature tells us 3 things:
- the function name
- how many parameters (inputs) and their types
- what type of return value is to be expected

```c
returnType functionName (type1 parameter1, type2 parameter2)
```
If a function isn't going to return any value, `void` is used as the return type. `void` indicates to the compiler that the function returns no data and should not expect to see the `return` keyword. Any of the types covered in previous lessons, `int`, `char`, `boolean`, etc, can be used as the return type of a function.

Similarly, if a function has no parameters `void` should be in place of any parameters. The parameters listed inside the parenthesis are like variable declarations. Each parameter should start with the type and then the name of the parameter.

The code statements "inside" the function are known as the body of the function and are enclosed with curly braces after the function signature.
```c
returnType functionName (type1 parameter1, type2 parameter2) {
  // code statement 1;
  // code statement 2;

return output;
}
```
The signature and the body are the two parts we need to create our own functions. 
```c
void makeCookie(){
  printf("Milk\n");
  printf("Flour\n");
  printf("Chocolate Chips\n");
  printf("Butter\n");
  printf("Thanks for the ingredients, here's a cookie!\n");
}
```

Defining Functions

Now that we know how to call functions, use their arguments and capture their return values, let's take a look at some functions provided by the C programming language.

C gives us access to many useful libraries that include many different functions for you to use. In order to have access to these functions you need to include header files like `<stdio.h>` and `<stdlib.h>`. 

You have already used `printf()` to output text to the console and learned about `abs()` to find the absolute value of an integer. Here are a few more functions we might use in your programs:
- `ceil()`: takes any number as an argument, rounds it up to the nearest integer, and returns the integer.
- `log()`: takes an integer as an argument and returns the natural logarithm of the given number.
- `toupper()`: takes a `char` as an argument and returns the uppercase of any alphabetic character.
- `isupper()`: takes a `char` as an argument and returns `1` if the character is an uppercase letter, `0` otherwise.

Let's use these functions in some code:
```c
#include <stdio.h>
#include <math.h>
#include <ctype.h>

int main() {
  float number = 4.5;
  char letter = 'a';
  printf("%f\n", ceil(number)); // 5.000000
  printf("%f\n", log(number)); // 1.504077
  printf("%d\n", isupper(letter)); // 0
  letter = toupper(letter);
  printf("%d\n", isupper(letter)); // 1
}
```
In the above example:
- The `math.h` and `ctype.h` libraries are used in this code.
- The `number` variable is passed to `ceil()` and output. The result is `5.000000`.
- The `number` variable is passed to `log()` and output. The result is `1.504077`.
- The `letter` variable is passed to `isupper()` and output. The result is `0` which represents False.
- The `letter` variable is passed to `toupper()` and assigned to `letter`.
- The new value in the `letter` variable is passed to `isupper()` and output. The result is `1` which represents True.

There are many useful functions contained in the C standard libraries. [Here is a list](https://www.ibm.com/docs/en/i/7.3?topic=extensions-standard-c-library-functions-table-by-name) of some of them. It is worth looking through them to see how they can help your code.





Library Functions

Great job learning about functions! We’ve managed to cover many important topics like:
- Functions are a named set of instructions 
- Functions can take in a set of inputs and produce some output
- Functions help you write DRY (**D**on't **R**epeat **Y**ourself) code
- C comes with many libraries that contain useful, ready-to-use functions
- Function calls can take arguments and return values
- Functions are made up of a function signature and body.
- `void` can be used as a return or parameter type
- A function returns a value with a `return` statement in the body 
- A function can have parameters that are placeholder variables for the function
- Pointers can be used as function parameters to help with memory management
- Function prototypes are good practice in C

With the help of functions, you can now build larger, cleaner projects.


Summary

As we've seen, the code `printf("Hello, World\n")` outputs the string between the parentheses to the console. The general usage of a function is to "call" the given name with a set of parentheses. Any input that is needed for the function is placed inside the parentheses.

These inputs are commonly known as the arguments of the function. Certain functions take no arguments, some take one and some take multiple. No matter the case, it is important to know what arguments a function expects so we use the correct values in the correct spots.

The `printf()` function can change its behavior based on the number of arguments it receives.
```c
#include <stdio.h>

printf("Hello, World!"); // Outputs: Hello, World!
int num = 9;
printf("My number is %d", num); // Outputs: My number is 9
```
In the example above, the first `printf()` call takes the string `"Hello, World!"` as an argument. The output is the string. The second `printf()` call takes two arguments, a string and a variable. The output this time is the string with the variable inserted where indicated by `%d`. These two uses of `printf()` show the flexibility that is allowed when using functions.

Lastly, a function can return its output, which can then be used further. For example:
```c
#include <stdio.h>
#include <stdlib.h>

int absValue = abs(-5);
printf("Absolute value of -5: %d\n", absValue);

// Output
// Absolute value of -5: 5
```
In the example above, we use a different function `abs()`, which returns the [absolute value](https://en.wikipedia.org/wiki/Absolute_value) of an integer passed as an argument. We are able to use this function by adding the line `#include <stdlib.h>` to the top of the code. 

As we can see, when we call `abs(-5)` we are assigning it to the integer `absValue`. This assigns the value returned by `abs(-5)` to the variable `absValue`. This is shown by outputting the value which is `5`.

Calling a Function

So far when we've called a function, we had to make sure that it is declared above the line in our code from where we are calling it. If not, the compiler will have not stored the function signature to check if the function call is correct in terms of return and parameter types.

Instead of making sure our functions are always declared above where they are called, a good practice is to define _function prototypes_ at the top of our code:
```c
#include <stdio.h>

// function prototypes
int upperFunction(int, int);
void lowerFunction(char*);

int upperFunction(int number1, int number2){
  int sum = number1 + number2;
  lowerFunction("The numbers have been added.");
  return sum;
}

void lowerFunction(char* string1) {
  printf("%s\n", string1);
} 

int main(){
  int sum = upperFunction(4, 2);
}
```
The above example shows 2 function prototypes toward the top of the code. The `main()` function calls `upperFunction()` which then calls `lowerFunction()`. `upperfunction()` "knows" about `lowerFunction()` due to the function prototypes at the top of the code. The compiler is made aware of each function signature before the entire body of the function is implemented.

One thing to note is that the names of the parameters associated with the function are not necessary for a function prototype. The compiler is concerned with 3 things when it comes to function prototypes:
- The function name
- The return type
- The parameter type(s)

Function prototypes are a good practice in C and they help you expand your code without any unforeseen errors due to the compiler not knowing a function signature.
