Function M-Files

References:

1. Hahn & Valentine, "Essential MATLAB for Engineers and Scientists", Fourth Edition, Chapter 10 up to section 10.3.3
2. "Computer Science 01", section 8.6.
3. Delores M. Etter, "Introduction to MATLAB, Second Edition", Section 3.6.

General

• Matlab function files are very similar to Matlab script files, with a few important differences.
• Both are plain ASCII files containing Matlab commands, with ".m" file extensions.
• Ordinary script files have the problem that they run in the scope of the command window. Any variables created get added to the workspace, and may replace other variables that were already defined there with the same names.
• Functions, however, define a separate ( local ) scope. Variables defined and used in a function do not affect the regular Matlab workspace.
• As a consequence, functions have mechanisms for passing arguments into the functions, and for returning the results.

Syntax

• The general syntax of a Matlab function is as follows:

        function [ outarg1, outarg2, ..., outargN ] = functionName( inarg1, inarg2, ..., inargM )
        % First comment line is reported by "lookfor"
        % Additional lines of first comment are reported by "help"
        .
        .	Matlab commands
        .
        outarg1 = . . .
        .
        .
        outargN = . . .
        .
        .
        .

Details

• Matlab functions must begin with the keyword "function"
• Matlab supports multiple output arguments ( i.e. multiple "return" values ), listed as shown in square brackets.
  • If a function only has a single output argument, then the square brackets are not required.
  • If a function does not have any output arguments, then neither the square brackets nor the equals sign that follows are used.
• The name of the function must match the name of the .m file containing the function. ( If not, then Matlab ignores the internal name, which just confuses everything. )
• Matlab supports multiple input arguments, in a comma separated list within parentheses as shown.
  • Data types are not specified for either input or output arguments.
  • Any type of data, including vectors and matrices, can be used for either input or output arguments.
  • All input arguments are passed by value.
    • Pass by reference can be simulated by storing the return value in the same variable that was passed to the function:
      • x = func( x );
  • If a function takes no input arguments, the empty parentheses are still required.
• The first comment line is searched by the "lookfor" command, and printed out if any words on the line match.
• The entire first comment block is displayed by "help" or "doc"
• Each of the output arguments needs to be assigned a value somewhere during the execution of the function.
• Functions normally return automatically when the end of the file ( function ) is reached. Alternatively the "return" statement can be used to force an early return, ( usually under the control of an "if" statement. )
• Local variables may be declared "persistent", which will cause them to remember their values from one function call to the next. ( Equivalent to "static" local variables in C/C++ )

Example

• quadratic.m evaluates a quadratic equation. Try saving the file to your working Matlab directory and then running "lookfor polynomial", "help quadratic", and "doc quadratic".

Checking the Number of Arguments Passed In or Out

• It is possible to call Matlab functions with a smaller number of arguments than what is defined in the function. ( For example, see "help rand" )
• In this case, the arguments passed are matched with the function arguments from the beginning of the arguments list. Omitted arguments are left off from the end of the list.
• From within the function, you can determine the actual number of arguments passed for input and for output with the special Matlab variables "nargin" and "nargout" respectively.

Subfunctions

• The first function in an m-file is the primary function, whose name must match the file name.
• Additional subfunctions may follow the primary function in the file.
  • The syntax of subfunctions is the same as for the primary function, except with different function names.
  • Subfunctions are only accessible from other functions within the same file.

Private Functions

• If a subdirectory is named "private", then functions in that directory are only accessible from functions in the parent directory of the private subdirectory.

P-Code Files

• Before Matlab code can be executed, it must be compiled, which creates a binary instruction version of the Matlab commands. Normally this occurs automatically as needed, and happens so fast that you never notice it.
• It is possible to pre-compile Matlab m-files into p-files, using the "pcode" command.
  • This will speed up execution, though in most cases the difference is negligible.
  • It also allows you to distribute the compiled version of your code, so that others can use it without seeing your original work.
  • Syntax: "pcode filename", where filename is the name of the m-file to be compiled.
• Unfortunately p-files are not visible to lookfor, help, or doc.

Function Handles

• A function handle is effectively a variable that tells Matlab where to find a particular function.
• Because they are variables, function handles can be used to access many different functions, and can even "point to" different functions as the program runs.
• The feval( ) function allows Matlab to call any function for which there is a handle set. The first argument to feval is a handle to a function, and the rest of the arguments are passed to the function when Matlab calls it.
• The @ symbol is used to generate a function handle from a function name, which can be either a Matlab built-in function or any available function from a .m file.
  • The function handle generated can be used directly in feval, or saved in a varaible to be used later.
• Function handles can also be passed to other functions, allowing one function to call another without knowing ahead of time what function is to be called.
  
  
• For example, suppose you have a function named "myFunction" in a file named "myFunction.m", which takes a single argument and returns a single value. The following Matlab function would use function handles to call three different functions, and return the sum of the results:

		function result = functionCaller( handle, x )
        
        	sinHandle = @sin;
        
        	result = feval( sinHandle, x ) + feval( @cos, x ) + feval( handle, x );
        
       	return; 

• When calling functionCaller one would pass a function handle in as the first argument, similar to the way they are passed to feval above. ( Note that the function the handle refers to must be callable using a single argument, since that is how it is being used in this example. If the function needed more arguments, then more arguments would have to be passed to feval. )