FUNCTION Function Declarations
Section: Functions and Scripts
Usage
There are several forms for function declarations in FreeMat. The most general syntax for a function declaration is the following:function [out_1,...,out_M,varargout] = fname(in_1,...,in_N,varargin)
where out_i
are the output parameters, in_i
are the input
parameters, and varargout
and varargin
are special keywords
used for functions that have variable inputs or outputs. For
functions with a fixed number of input or output parameters, the
syntax is somewhat simpler:
function [out_1,...,out_M] = fname(in_1,...,in_N)
Note that functions that have no return arguments can omit
the return argument list (of out_i
) and the equals sign:
function fname(in_1,...,in_N)
Likewise, a function with no arguments can eliminate the list of parameters in the declaration:
function [out_1,...,out_M] = fname
Functions that return only a single value can omit the brackets
function out_1 = fname(in_1,...,in_N)
In the body of the function in_i
are initialized with the
values passed when the function is called. Also, the function
must assign values for out_i
to pass values to the caller.
Note that by default, FreeMat passes arguments by value, meaning
that if we modify the contents of in_i
inside the function,
it has no effect on any variables used by the caller. Arguments
can be passed by reference by prepending an ampersand &
before the name of the input, e.g.
function [out1,...,out_M] = fname(in_1,&in_2,in_3,...,in_N)
in which case in_2
is passed by reference and not by value.
Also, FreeMat works like C
in that the caller does not have
to supply the full list of arguments. Also, when keywords
(see help keywords
) are used, an arbitrary subset of the
parameters may be unspecified. To assist in deciphering
the exact parameters that were passed,
FreeMat also defines two variables inside the function context:
nargin
and nargout
, which provide the number of input
and output parameters of the caller, respectively. See help for
nargin
and nargout
for more details. In some
circumstances, it is necessary to have functions that
take a variable number of arguments, or that return a variable
number of results. In these cases, the last argument to the
parameter list is the special argument varargin
. Inside
the function, varargin
is a cell-array that contains
all arguments passed to the function that have not already
been accounted for. Similarly, the function can create a
cell array named varargout
for variable length output lists.
See help varargin
and varargout
for more details.
The function name fname
can be any legal FreeMat identifier.
Functions are stored in files with the .m
extension. Note
that the name of the file (and not the function name fname
used in the declaration) is how the function appears in FreeMat.
So, for example, if the file is named foo.m
, but the declaration
uses bar
for the name of the function, in FreeMat, it will
still appear as function foo
. Note that this is only true
for the first function that appears in a .m
file. Additional
functions that appear after the first function are known as
helper functions
or local
functions. These are functions that
can only be called by other functions in the same .m
file. Furthermore
the names of these helper functions are determined by their declaration
and not by the name of the .m
file. An example of using
helper functions is included in the examples.
Another important feature of functions, as opposed to, say scripts
,
is that they have their own scope
. That means that variables
defined or modified inside a function do not affect the scope of the
caller. That means that a function can freely define and use variables
without unintentionally using a variable name reserved elsewhere. The
flip side of this fact is that functions are harder to debug than
scripts without using the keyboard
function, because the intermediate
calculations used in the function are not available once the function
exits.
Examples
Here is an example of a trivial function that adds its first argument to twice its second argument:
addtest.m function c = addtest(a,b) c = a + 2*b;
--> addtest(1,3) ans = 7 --> addtest(3,0) ans = 3
Suppose, however, we want to replace the value of the first argument by the computed sum. A first attempt at doing so has no effect:
addtest2.m function addtest2(a,b) a = a + 2*b;
--> arg1 = 1 arg1 = 1 --> arg2 = 3 arg2 = 3 --> addtest2(arg1,arg2) --> arg1 ans = 1 --> arg2 ans = 3
The values of arg1
and arg2
are unchanged, because they are
passed by value, so that any changes to a
and b
inside
the function do not affect arg1
and arg2
. We can change
that by passing the first argument by reference:
addtest3.m function addtest3(&a,b) a = a + 2*b
Note that it is now illegal to pass a literal value for a
when
calling addtest3
:
--> addtest3(3,4) a = 11 Error: Must have lvalue in argument passed by reference --> addtest3(arg1,arg2) a = 7 --> arg1 ans = 7 --> arg2 ans = 3
The first example fails because we cannot pass a literal like the
number 3
by reference. However, the second call succeeds, and
note that arg1
has now changed. Note: please be careful when
passing by reference - this feature is not available in MATLAB
and you must be clear that you are using it.
As variable argument and return functions are covered elsewhere,
as are keywords, we include one final example that demonstrates
the use of helper functions, or local functions, where
multiple function declarations occur in the same file.
euclidlength.m function y = foo(x,y) square_me(x); square_me(y); y = sqrt(x+y); function square_me(&t) t = t^2;
--> euclidlength(3,4) ans = 5 --> euclidlength(2,0) ans = 2