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
|
<!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: KEYWORDS Function Keywords</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_keywords.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">KEYWORDS Function Keywords </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>A feature of IDL that FreeMat has adopted is a modified form of <code>keywords</code>. The purpose of <code>keywords</code> is to allow you to call a function with the arguments to the function specified in an arbitrary order. To specify the syntax of <code>keywords</code>, suppose there is a function with prototype </p>
<pre class="fragment"> function [out_1,...,out_M] = foo(in_1,...,in_N)
</pre><p> Then the general syntax for calling function <code>foo</code> using keywords is </p>
<pre class="fragment"> foo(val_1, val_2, /in_k=3)
</pre><p> which is exactly equivalent to </p>
<pre class="fragment"> foo(val_1, val_2, [], [], ..., [], 3),
</pre><p> where the 3 is passed as the k-th argument, or alternately, </p>
<pre class="fragment"> foo(val_1, val_2, /in_k)
</pre><p> which is exactly equivalent to </p>
<pre class="fragment"> foo(val_1, val_2, [], [], ..., [], logical(1)),
</pre><p> Note that you can even pass reference arguments using keywords. </p>
<h1><a class="anchor" id="Example"></a>
Example</h1>
<p>The most common use of keywords is in controlling options for functions. For example, the following function takes a number of binary options that control its behavior. For example, consider the following function with two arguments and two options. The function has been written to properly use and handle keywords. The result is much cleaner than the MATLAB approach involving testing all possible values of <code>nargin</code>, and forcing explicit empty brackets for don't care parameters.</p>
<pre class="fragment"> keyfunc.m
</pre><pre class="fragment">function c = keyfunc(a,b,operation,printit)
if (~isset('a') | ~isset('b'))
error('keyfunc requires at least the first two 2 arguments');
end;
if (~isset('operation'))
% user did not define the operation, default to '+'
operation = '+';
end
if (~isset('printit'))
% user did not specify the printit flag, default is false
printit = 0;
end
% simple operation...
eval(['c = a ' operation ' b;']);
if (printit)
printf('%f %s %f = %f\n',a,operation,b,c);
end
</pre><p>Now some examples of how this function can be called using <code>keywords</code>.</p>
<pre class="fragment">--> keyfunc(1,3) % specify a and b, defaults for the others
ans =
4
--> keyfunc(1,3,/printit) % specify printit is true
1.000000 + 3.000000 = 4.000000
ans =
4
--> keyfunc(/operation='-',2,3) % assigns a=2, b=3
ans =
-1
--> keyfunc(4,/operation='*',/printit) % error as b is unspecified
In /home/sbasu/Devel/FreeMat4/doc/fragments/keyfunc.m(keyfunc) at line 3
In scratch() at line 1
In base(base)
In base()
In global()
Error: keyfunc requires at least the first two 2 arguments
</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>
|
