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
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>FreeMat: FUNCTION Function Declarations</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">FreeMat
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.1 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
</ul>
</div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('functions_function.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">FUNCTION Function Declarations </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Section: <a class="el" href="sec_functions.html">Functions and Scripts</a> </p>
<h1><a class="anchor" id="Usage"></a>
Usage</h1>
<p>There are several forms for function declarations in FreeMat. The most general syntax for a function declaration is the following: </p>
<pre class="fragment"> 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: </p>
<pre class="fragment"> 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: </p>
<pre class="fragment"> function fname(in_1,...,in_N)
</pre><p> Likewise, a function with no arguments can eliminate the list of parameters in the declaration: </p>
<pre class="fragment"> function [out_1,...,out_M] = fname
</pre><p> Functions that return only a single value can omit the brackets </p>
<pre class="fragment"> 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. </p>
<pre class="fragment"> 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.</p>
<p>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.</p>
<p>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. </p>
<h1><a class="anchor" id="Examples"></a>
Examples</h1>
<p>Here is an example of a trivial function that adds its first argument to twice its second argument:</p>
<pre class="fragment"> addtest.m
</pre><pre class="fragment">function c = addtest(a,b)
c = a + 2*b;
</pre><pre class="fragment">--> 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 class="fragment"> addtest2.m
</pre><pre class="fragment">function addtest2(a,b)
a = a + 2*b;
</pre><pre class="fragment">--> 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 class="fragment"> addtest3.m
</pre><pre class="fragment">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>:</p>
<pre class="fragment">--> 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.</p>
<p>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 class="fragment"> euclidlength.m
</pre><pre class="fragment">function y = foo(x,y)
square_me(x);
square_me(y);
y = sqrt(x+y);
function square_me(&t)
t = t^2;
</pre><pre class="fragment">--> euclidlength(3,4)
ans =
5
--> euclidlength(2,0)
ans =
2
</pre> </div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a class="el" href="index.html">FreeMat Documentation</a></li><li class="navelem"><a class="el" href="sec_functions.html">Functions and Scripts</a></li>
<li class="footer">Generated on Thu Jul 25 2013 18:58:17 for FreeMat by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.1.1 </li>
</ul>
</div>
</body>
</html>
|
