Function Files

You may define your own functions in m-files named functionname.m.

function s = squares(high)

%SQUARES Make a vector of squares.

%squares(high) returns (1:high)

temp = 1:high;

s = temp. temp;

This (in squares.m) may then be used as any function;

.1ex>> sq = squares(5)
sq =
You will note that squares.m puts semicolons after each line; if it did not, every time it was called it would echo the result of each line of computation, which is extremely annoying.

A more sophisticated version of such a function could be

function [y x] = powers(high, p)

%POWERS Table of some power of n versus n.

% powers(high, p) returns [1:high] to the pth (elementwise)

% powers(high) returns the square

if nargin < 2, p = 2; end;

y = [1:high]. p;

if nargout > 1, x = 1:high;

end

.1ex>> [y x] = powers(4, 3)
y =

x =

.1ex>> y = powers(4, 3)
y =

.1ex>> [y x] = powers(4)
y =

x =

This function would be placed in the file powers.m; a function must always be in an m-file of the same name (.m).

In this example, more than one argument can be given, but the second is optional; the special variable nargin is consulted to see how many arguments were passed to the function, and the second is given a default value if omitted. There may also be more than one output value, and the special value nargout is checked to see how many assignments should be carried out. Use nargchk to confirm that nargin is in a valid specified range.

The character % at the beginning of a line indicates a comment. The set of commented lines after the function line is returned by help functionname, so it is important that they exist and document the function's behavior. The first line is what lookfor examines, so it should be the name and a concise summary.

A function need not return anything; many plotting functions do not. For these the first line is of the form function functionname(arguments).

Encountering the return command causes the function to terminate and sends control back to what invoked the function.

Variables within a function exist only within the function; changing them does not affect any variables of the same name in the workspace, nor does referencing them reference variables of the same name in the workspace (or in other functions). This is not always the desired behavior. If you wish some variable to be used in more than one area, global variable1 variable2... in each such area. Any assignment to a variable declared global in one area affects the value of that variable in all areas in which it is declared global. isglobal will test if a given variable is global in an area; who(s) global will list the global variables.

If you wish your function to be able to take a function as argument, you should take its name and apply feval('functionname', arguments for function), which will evaluate the function of that name with those arguments.

Useful operations for functions include pause, which waits argument seconds, or for the user to strike any key given no argument (pause off and pause on change whether pause should be ignored); keyboard, which passes control to the keyboard (using a K.2ex>> prompt as indication) until RETURN is entered; and error and input for which see  Text.

As with scripts, echo can be used to have the text of a function file be echoed when the function is invoked. echo functionname on and echo functionname off will turn echoing on and off for a single file, while echo functionname will toggle. echo on all and echo off all affect echoing of all function files.