M-File Programming (Programming and Data Types)

Programming and Data Types

Basic Parts of a Function M-File

A function M-file consists of:

This section also covers the following topics:

The Function Definition Line

The function definition line informs MATLAB that the M-file contains a function, and specifies the argument calling sequence of the function. The function definition line for the average function is

All MATLAB functions have a function definition line that follows this pattern.

The Function Name. MATLAB function names have the same constraints as variable names. The name must begin with a letter, which may be followed by any combination of letters, digits, and underscores. Making all letters in the name lowercase is recommended as it makes your M-files portable between platforms.

Although function names can be of any length, MATLAB uses only the first N characters of the name, (where N is the number returned by the function namelengthmax), and ignores the rest. Hence, it is important to make each function name unique in the first N characters.

```
N = namelengthmax
N =
    63
```

Note Some operating systems may restrict function names to shorter lengths.

The name of the text file that contains a MATLAB function consists of the function name with the extension .m appended. For example,

```
average.m
```

If the filename and the function definition line name are different, the internal (function) name is ignored. Thus, if average.m is the file that defines a function named compute_average, you would invoke the function by typing

```
average
```

Note While the function name specified on the function definition line does not have to be the same as the filename, we strongly recommend that you use the same name for both.

Function Arguments. If the function has multiple output values, enclose the output argument list in square brackets. Input arguments, if present, are enclosed in parentheses. Use commas to separate multiple input or output arguments. Here's a more complicated example.

function [x, y, z] = sphere(theta, phi, rho)

If there is no output, leave the output blank

```
function printresults(x)
```

or use empty square brackets

```
function [] = printresults(x)
```

The variables that you pass to the function do not need to have the same name as those in the function definition line.

The H1 Line

The H1 line, so named because it is the first help text line, is a comment line immediately following the function definition line. Because it consists of comment text, the H1 line begins with a percent sign, "%." For the average function, the H1 line is

```
% AVERAGE Mean of vector elements.
```

This is the first line of text that appears when a user types help function_name at the MATLAB prompt. Further, the lookfor function searches on and displays only the H1 line. Because this line provides important summary information about the M-file, it is important to make it as descriptive as possible.

Help Text

You can create online help for your M-files by entering text on one or more comment lines, beginning with the line immediately following the H1 line. The help text for the average function is

% AVERAGE(X), where X is a vector, is the mean of vector elements.
% Nonvector input results in an error.

When you type help function_name, MATLAB displays the comment lines that appear between the function definition line and the first non-comment (executable or blank) line. The help system ignores any comment lines that appear after this help block.

For example, typing help sin results in

SIN     Sine.
        SIN(X) is the sine of the elements of X.

The Function Body

The function body contains all the MATLAB code that performs computations and assigns values to output arguments. The statements in the function body can consist of function calls, programming constructs like flow control and interactive input/output, calculations, assignments, comments, and blank lines.

For example, the body of the average function contains a number of simple programming statements.

[m,n] = size(x);
if (~((m == 1) | (n == 1)) | (m == 1 & n == 1)) % Flow control
    error('Input must be a vector') % Error message display
end
y = sum(x)/length(x);             % Computation and assignment

Comments

As mentioned earlier, comment lines begin with a percent sign (%). Comment lines can appear anywhere in an M-file, and you can append comments to the end of a line of code. For example,

% Add up all the vector elements.
y = sum(x)           % Use the sum function.

The first comment line immediately following the function definition line is considered the H1 line for the function. The H1 line and any comment lines immediately following it constitute the online help entry for the file.

In addition to comment lines, you can insert blank lines anywhere in an M-file. Blank lines are ignored. However, a blank line can indicate the end of the help text entry for an M-file.

Functions How Functions Work