5.2.1: Function Case Study (Lambert)

By Adam Lambert, Zero to MATLAB, 8.1 Basic Functions

Generally, when we make a function we will be using two separate m-files. One m-file will contain the code for the function. A 2nd file (the test file) will call the function.

Two notes of caution:

1. Do not try to run a function file by itself. A function file is different from a script file. If you do try to run a function file, MATLAB or Octave will usually complain that the inputs are not defined. You need to call the function from the test script file.

2. Do not "clear all" inside the function. That would clear your inputs and the function will fail. Only "clear all" in the test script file.

The function syntax can be confusing at first. In simple problems it can seem pointless to implement a function, but  you want to practice creating functions with simple problems. As you begin to write more complex programs, functions become a valuable tool. Take the time to learn the operation with these simple examples.

The syntax required to build a function is the most complex that we have encountered. It takes some practice to get it organized in your head. Let's dive into a simple example and take some time to discuss all of the pieces.

Example \(\PageIndex{1}\) times_two function

This is a function which will accept a number as input, multiply it by two, and return the result of that calculation as output. This code should be saved in an m-file called times_two.m. The name of the function must be the same as the m-file where it is stored.

function y = times_two(x)
    y = 2*x;
end

On the first line we see the function command, followed by the expression y = times_two(x). We call this line the declaration. (Some authors call this the function declaration; others call it the function signature. Both declaration and signature mean the same thing.) The function command tells MATLAB that this code is a function. It must be the first command in the file.

The variable x is the input variable for the function. Whatever number that we pass to the function will be assigned to the variable x which can then be used in the calculations inside the function. The variable y to the left of the assignment operator is the output variable. This value must be assigned during the execution of the function. In this simple case, the assignment is the only expression inside the function. As long as the variable is assigned within the function, then the value of the variable will be returned once the code inside the function completes.

The name of the function, times_two, is also the command that we use to execute the function. When we execute a function, we say that we call the function. A line of code in a script that calls a function is often referred to as a function call. In order to call a function, the m-file must be saved in the current directory.

If you look at the structure of the declaration, you can see that it mimics the structure of the code which is used to call it. The output variable is in the position to be assigned a value, and the input variable is in the position to pass a value into the function. Consider this similar expression using a built-in command:

>>z = sin(pi)

The value of pi is passed into the sin function and the result is assigned to the variable z. The declaration of this function would look like this.

function y = sin(x)

Inside there would be an algorithm to calculate the sine of the value of x and assign it to the variable y.

Now that we've had an overview of how functions are made and implemented, let's practice with this simple example to learn more about the behavior.

1. Open up a new m-file and save it in the current directory as times two.m.

2. Type the code from the times two example into the script and save it. Note that the file name and the function name are the same.

3. Now go to the Command Window and call the function at the prompt. We need to input a number, just like if we used one of the trigonometric functions.

>>times two(4)

The function will return the value 8. Note that the variable y is not saved in the Workspace and the value is assigned to the default variable name ans. If you do have a variable y from a previous calculation then clear the Workspace and try again. This is important, because the function only returns a value, not a variable. We'll discuss this in more detail in the next section.

4. We can use a variable to pass the input value into the function. We can also use a variable to store the returned results. Try the following sequence in the Command Window.

>>a = 4;
>>b = times two(a);

Note that the variable names are not the same as the names inside the function. They do not have to be, because they are simply passing values in and out of the function. The external variables never interact with the code inside the function.

Let's look back at the code in times two.m and walk through the whole process. First, the input value is assigned to the variable x. This can occur with a number or a variable. If the input to the function is a variable, then MATLAB will look up the value and assign that value to the variable x. Once the variable x is defined, then the code will execute. In this case, x will be multiplied by 2 and the result assigned the to variable y. Then, because all of the code inside the function has completed, the value of the output variable will be returned.

This is the most complex topic that we have covered, so don't be discouraged if this is confusing the first time through. As we move through the chapter and you get more experience, the flow of information will be easier to see.

Solution

Add example text here.