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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<TITLE>KEYWORDS Function Keywords
</TITLE>
</HEAD>
<BODY>
<H2>KEYWORDS Function Keywords
</H2>
<P>
Section: <A HREF=sec_functions.html> Functions and Scripts </A>
<H3>Usage</H3>
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
<PRE>
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
<PRE>
foo(val_1, val_2, /in_k=3)
</PRE>
<P>
which is exactly equivalent to
<PRE>
foo(val_1, val_2, [], [], ..., [], 3),
</PRE>
<P>
where the 3 is passed as the k-th argument, or alternately,
<PRE>
foo(val_1, val_2, /in_k)
</PRE>
<P>
which is exactly equivalent to
<PRE>
foo(val_1, val_2, [], [], ..., [], logical(1)),
</PRE>
<P>
Note that you can even pass reference arguments using keywords.
<H3>Example</H3>
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>
keyfunc.m
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>.
<PRE>
--> 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/basu/dev/branches/FreeMat4/help/tmp/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>
<P>
</BODY>
</HTML>
|
