1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<TITLE>FUNCTION Function Declarations
</TITLE>
</HEAD>
<BODY>
<H2>FUNCTION Function Declarations
</H2>
<P>
Section: <A HREF=sec_functions.html> Functions and Scripts </A>
<H3>Usage</H3>
There are several forms for function declarations in FreeMat.
The most general syntax for a function declaration is the
following:
<PRE>
function [out_1,...,out_M,varargout] = fname(in_1,...,in_N,varargin)
</PRE>
<P>
where <code>out_i</code> are the output parameters, <code>in_i</code> are the input
parameters, and <code>varargout</code> and <code>varargin</code> 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:
<PRE>
function [out_1,...,out_M] = fname(in_1,...,in_N)
</PRE>
<P>
Note that functions that have no return arguments can omit
the return argument list (of <code>out_i</code>) and the equals sign:
<PRE>
function fname(in_1,...,in_N)
</PRE>
<P>
Likewise, a function with no arguments can eliminate the list
of parameters in the declaration:
<PRE>
function [out_1,...,out_M] = fname
</PRE>
<P>
Functions that return only a single value can omit the brackets
<PRE>
function out_1 = fname(in_1,...,in_N)
</PRE>
<P>
In the body of the function <code>in_i</code> are initialized with the
values passed when the function is called. Also, the function
must assign values for <code>out_i</code> to pass values to the caller.
Note that by default, FreeMat passes arguments by value, meaning
that if we modify the contents of <code>in_i</code> inside the function,
it has no effect on any variables used by the caller. Arguments
can be passed by reference by prepending an ampersand <code>&</code>
before the name of the input, e.g.
<PRE>
function [out1,...,out_M] = fname(in_1,&in_2,in_3,...,in_N)
</PRE>
<P>
in which case <code>in_2</code> is passed by reference and not by value.
Also, FreeMat works like <code>C</code> in that the caller does not have
to supply the full list of arguments. Also, when <code>keywords</code>
(see help <code>keywords</code>) 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:
<code>nargin</code> and <code>nargout</code>, which provide the number of input
and output parameters of the caller, respectively. See help for
<code>nargin</code> and <code>nargout</code> 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 <code>varargin</code>. Inside
the function, <code>varargin</code> 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 <code>varargout</code> for variable length output lists.
See help <code>varargin</code> and <code>varargout</code> for more details.
The function name <code>fname</code> can be any legal FreeMat identifier.
Functions are stored in files with the <code>.m</code> extension. Note
that the name of the file (and not the function name <code>fname</code>
used in the declaration) is how the function appears in FreeMat.
So, for example, if the file is named <code>foo.m</code>, but the declaration
uses <code>bar</code> for the name of the function, in FreeMat, it will
still appear as function <code>foo</code>. Note that this is only true
for the first function that appears in a <code>.m</code> file. Additional
functions that appear after the first function are known as
<code>helper functions</code> or <code>local</code> functions. These are functions that
can only be called by other functions in the same <code>.m</code> file. Furthermore
the names of these helper functions are determined by their declaration
and not by the name of the <code>.m</code> file. An example of using
helper functions is included in the examples.
Another important feature of functions, as opposed to, say <code>scripts</code>,
is that they have their own <code>scope</code>. 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 <code>keyboard</code> function, because the intermediate
calculations used in the function are not available once the function
exits.
<H3>Examples</H3>
Here is an example of a trivial function that adds its
first argument to twice its second argument:
<P>
<PRE>
addtest.m
function c = addtest(a,b)
c = a + 2*b;
</PRE>
<P>
<PRE>
--> addtest(1,3)
ans =
7
--> addtest(3,0)
ans =
3
</PRE>
<P>
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:
<P>
<PRE>
addtest2.m
function addtest2(a,b)
a = a + 2*b;
</PRE>
<P>
<PRE>
--> arg1 = 1
arg1 =
1
--> arg2 = 3
arg2 =
3
--> addtest2(arg1,arg2)
--> arg1
ans =
1
--> arg2
ans =
3
</PRE>
<P>
The values of <code>arg1</code> and <code>arg2</code> are unchanged, because they are
passed by value, so that any changes to <code>a</code> and <code>b</code> inside
the function do not affect <code>arg1</code> and <code>arg2</code>. We can change
that by passing the first argument by reference:
<P>
<PRE>
addtest3.m
function addtest3(&a,b)
a = a + 2*b
</PRE>
<P>
Note that it is now illegal to pass a literal value for <code>a</code> when
calling <code>addtest3</code>:
<PRE>
--> 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
</PRE>
<P>
The first example fails because we cannot pass a literal like the
number <code>3</code> by reference. However, the second call succeeds, and
note that <code>arg1</code> 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.
<P>
<PRE>
euclidlength.m
function y = foo(x,y)
square_me(x);
square_me(y);
y = sqrt(x+y);
function square_me(&t)
t = t^2;
</PRE>
<P>
<PRE>
--> euclidlength(3,4)
ans =
5
--> euclidlength(2,0)
ans =
2
</PRE>
<P>
</BODY>
</HTML>
|
