Mercurial > octave-nkf
annotate doc/interpreter/func.txi @ 19630:0e1f5a750d00
maint: Periodic merge of gui-release to default.
author | John W. Eaton <jwe@octave.org> |
---|---|
date | Tue, 20 Jan 2015 10:24:46 -0500 |
parents | e97c63531e76 fe689210525c |
children | db92e7e28e1f |
rev | line source |
---|---|
17744
d63878346099
maint: Update copyright notices for release.
John W. Eaton <jwe@octave.org>
parents:
17281
diff
changeset
|
1 @c Copyright (C) 1996-2013 John W. Eaton |
7018 | 2 @c |
3 @c This file is part of Octave. | |
4 @c | |
5 @c Octave is free software; you can redistribute it and/or modify it | |
6 @c under the terms of the GNU General Public License as published by the | |
7 @c Free Software Foundation; either version 3 of the License, or (at | |
8 @c your option) any later version. | |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18535
diff
changeset
|
9 @c |
7018 | 10 @c Octave is distributed in the hope that it will be useful, but WITHOUT |
11 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
12 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
13 @c for more details. | |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18535
diff
changeset
|
14 @c |
7018 | 15 @c You should have received a copy of the GNU General Public License |
16 @c along with Octave; see the file COPYING. If not, see | |
17 @c <http://www.gnu.org/licenses/>. | |
3294 | 18 |
4167 | 19 @node Functions and Scripts |
9032
349616d9c38e
Cleanup top-level documentation menu in octave.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
20 @chapter Functions and Scripts |
3294 | 21 @cindex defining functions |
22 @cindex user-defined functions | |
23 @cindex functions, user-defined | |
24 @cindex script files | |
25 | |
26 Complicated Octave programs can often be simplified by defining | |
27 functions. Functions can be defined directly on the command line during | |
28 interactive Octave sessions, or in external files, and can be called just | |
29 like built-in functions. | |
30 | |
31 @menu | |
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
32 * Introduction to Function and Script Files:: |
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
33 * Defining Functions:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
34 * Multiple Return Values:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
35 * Variable-length Argument Lists:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
36 * Ignoring Arguments:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
37 * Variable-length Return Lists:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
38 * Returning from a Function:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
39 * Default Arguments:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
40 * Function Files:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
41 * Script Files:: |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
42 * Function Handles Anonymous Functions Inline Functions:: |
6549 | 43 * Commands:: |
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
44 * Organization of Functions:: |
3294 | 45 @end menu |
46 | |
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
47 @node Introduction to Function and Script Files |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
48 @section Introduction to Function and Script Files |
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
49 |
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
50 There are seven different things covered in this section. |
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
51 @enumerate |
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
52 @item |
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
53 Typing in a function at the command prompt. |
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
54 |
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
55 @item |
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
56 Storing a group of commands in a file --- called a script file. |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
57 |
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
58 @item |
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
59 Storing a function in a file---called a function file. |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
60 |
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
61 @item |
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
62 Subfunctions in function files. |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
63 |
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
64 @item |
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
65 Multiple functions in one script file. |
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
66 |
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
67 @item |
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
68 Private functions. |
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
69 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
70 @item |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
71 Nested functions. |
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
72 @end enumerate |
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
73 |
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
74 Both function files and script files end with an extension of .m, for |
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
75 @sc{matlab} compatibility. If you want more than one independent |
14442
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
76 functions in a file, it must be a script file (@pxref{Script Files}), |
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
77 and to use these functions you must execute the script file before you |
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
78 can use the functions that are in the script file. |
c1f9b54350f9
doc: improve description of functions and scripts
Doug Stewart <doug.dastew@gmail.com>
parents:
14175
diff
changeset
|
79 |
4167 | 80 @node Defining Functions |
3294 | 81 @section Defining Functions |
82 @cindex @code{function} statement | |
83 @cindex @code{endfunction} statement | |
84 | |
85 In its simplest form, the definition of a function named @var{name} | |
86 looks like this: | |
87 | |
88 @example | |
89 @group | |
90 function @var{name} | |
91 @var{body} | |
92 endfunction | |
93 @end group | |
94 @end example | |
95 | |
96 @noindent | |
97 A valid function name is like a valid variable name: a sequence of | |
98 letters, digits and underscores, not starting with a digit. Functions | |
99 share the same pool of names as variables. | |
100 | |
101 The function @var{body} consists of Octave statements. It is the | |
102 most important part of the definition, because it says what the function | |
103 should actually @emph{do}. | |
104 | |
105 For example, here is a function that, when executed, will ring the bell | |
106 on your terminal (assuming that it is possible to do so): | |
107 | |
108 @example | |
109 @group | |
110 function wakeup | |
111 printf ("\a"); | |
112 endfunction | |
113 @end group | |
114 @end example | |
115 | |
116 The @code{printf} statement (@pxref{Input and Output}) simply tells | |
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
17152
diff
changeset
|
117 Octave to print the string @qcode{"\a"}. The special character @samp{\a} |
3294 | 118 stands for the alert character (ASCII 7). @xref{Strings}. |
119 | |
120 Once this function is defined, you can ask Octave to evaluate it by | |
121 typing the name of the function. | |
122 | |
123 Normally, you will want to pass some information to the functions you | |
124 define. The syntax for passing parameters to a function in Octave is | |
125 | |
126 @example | |
127 @group | |
128 function @var{name} (@var{arg-list}) | |
129 @var{body} | |
130 endfunction | |
131 @end group | |
132 @end example | |
133 | |
134 @noindent | |
135 where @var{arg-list} is a comma-separated list of the function's | |
136 arguments. When the function is called, the argument names are used to | |
137 hold the argument values given in the call. The list of arguments may | |
138 be empty, in which case this form is equivalent to the one shown above. | |
139 | |
140 To print a message along with ringing the bell, you might modify the | |
6510 | 141 @code{wakeup} to look like this: |
3294 | 142 |
143 @example | |
144 @group | |
145 function wakeup (message) | |
146 printf ("\a%s\n", message); | |
147 endfunction | |
148 @end group | |
149 @end example | |
150 | |
151 Calling this function using a statement like this | |
152 | |
153 @example | |
154 wakeup ("Rise and shine!"); | |
155 @end example | |
156 | |
157 @noindent | |
158 will cause Octave to ring your terminal's bell and print the message | |
159 @samp{Rise and shine!}, followed by a newline character (the @samp{\n} | |
160 in the first argument to the @code{printf} statement). | |
161 | |
162 In most cases, you will also want to get some information back from the | |
163 functions you define. Here is the syntax for writing a function that | |
164 returns a single value: | |
165 | |
166 @example | |
167 @group | |
168 function @var{ret-var} = @var{name} (@var{arg-list}) | |
169 @var{body} | |
170 endfunction | |
171 @end group | |
172 @end example | |
173 | |
174 @noindent | |
175 The symbol @var{ret-var} is the name of the variable that will hold the | |
176 value to be returned by the function. This variable must be defined | |
177 before the end of the function body in order for the function to return | |
178 a value. | |
179 | |
180 Variables used in the body of a function are local to the | |
181 function. Variables named in @var{arg-list} and @var{ret-var} are also | |
182 local to the function. @xref{Global Variables}, for information about | |
183 how to access global variables inside a function. | |
184 | |
185 For example, here is a function that computes the average of the | |
186 elements of a vector: | |
187 | |
188 @example | |
189 @group | |
190 function retval = avg (v) | |
191 retval = sum (v) / length (v); | |
192 endfunction | |
193 @end group | |
194 @end example | |
195 | |
196 If we had written @code{avg} like this instead, | |
197 | |
198 @example | |
199 @group | |
200 function retval = avg (v) | |
4029 | 201 if (isvector (v)) |
3294 | 202 retval = sum (v) / length (v); |
203 endif | |
204 endfunction | |
205 @end group | |
206 @end example | |
207 | |
208 @noindent | |
209 and then called the function with a matrix instead of a vector as the | |
210 argument, Octave would have printed an error message like this: | |
211 | |
212 @example | |
213 @group | |
8015
30629059b72d
Update the manual to reflect the changes in error output
sh@sh-laptop
parents:
7984
diff
changeset
|
214 error: value on right hand side of assignment is undefined |
3294 | 215 @end group |
216 @end example | |
217 | |
218 @noindent | |
219 because the body of the @code{if} statement was never executed, and | |
220 @code{retval} was never defined. To prevent obscure errors like this, | |
221 it is a good idea to always make sure that the return variables will | |
222 always have values, and to produce meaningful error messages when | |
223 problems are encountered. For example, @code{avg} could have been | |
224 written like this: | |
225 | |
226 @example | |
227 @group | |
228 function retval = avg (v) | |
229 retval = 0; | |
4029 | 230 if (isvector (v)) |
3294 | 231 retval = sum (v) / length (v); |
232 else | |
233 error ("avg: expecting vector argument"); | |
234 endif | |
235 endfunction | |
236 @end group | |
237 @end example | |
238 | |
239 There is still one additional problem with this function. What if it is | |
240 called without an argument? Without additional error checking, Octave | |
241 will probably print an error message that won't really help you track | |
242 down the source of the error. To allow you to catch errors like this, | |
243 Octave provides each function with an automatic variable called | |
244 @code{nargin}. Each time a function is called, @code{nargin} is | |
245 automatically initialized to the number of arguments that have actually | |
246 been passed to the function. For example, we might rewrite the | |
247 @code{avg} function like this: | |
248 | |
249 @example | |
250 @group | |
251 function retval = avg (v) | |
252 retval = 0; | |
253 if (nargin != 1) | |
254 usage ("avg (vector)"); | |
255 endif | |
4029 | 256 if (isvector (v)) |
3294 | 257 retval = sum (v) / length (v); |
258 else | |
259 error ("avg: expecting vector argument"); | |
260 endif | |
261 endfunction | |
262 @end group | |
263 @end example | |
264 | |
265 Although Octave does not automatically report an error if you call a | |
266 function with more arguments than expected, doing so probably indicates | |
267 that something is wrong. Octave also does not automatically report an | |
268 error if a function is called with too few arguments, but any attempt to | |
269 use a variable that has not been given a value will result in an error. | |
270 To avoid such problems and to provide useful messages, we check for both | |
271 possibilities and issue our own error message. | |
272 | |
4700 | 273 @DOCSTRING(nargin) |
3294 | 274 |
6558 | 275 @DOCSTRING(inputname) |
276 | |
3371 | 277 @DOCSTRING(silent_functions) |
3294 | 278 |
4167 | 279 @node Multiple Return Values |
3294 | 280 @section Multiple Return Values |
281 | |
282 Unlike many other computer languages, Octave allows you to define | |
283 functions that return more than one value. The syntax for defining | |
284 functions that return multiple values is | |
285 | |
286 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
287 @group |
3294 | 288 function [@var{ret-list}] = @var{name} (@var{arg-list}) |
289 @var{body} | |
290 endfunction | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
291 @end group |
3294 | 292 @end example |
293 | |
294 @noindent | |
295 where @var{name}, @var{arg-list}, and @var{body} have the same meaning | |
296 as before, and @var{ret-list} is a comma-separated list of variable | |
297 names that will hold the values returned from the function. The list of | |
298 return values must have at least one element. If @var{ret-list} has | |
299 only one element, this form of the @code{function} statement is | |
300 equivalent to the form described in the previous section. | |
301 | |
302 Here is an example of a function that returns two values, the maximum | |
303 element of a vector and the index of its first occurrence in the vector. | |
304 | |
305 @example | |
306 @group | |
307 function [max, idx] = vmax (v) | |
308 idx = 1; | |
309 max = v (idx); | |
310 for i = 2:length (v) | |
311 if (v (i) > max) | |
312 max = v (i); | |
313 idx = i; | |
314 endif | |
315 endfor | |
316 endfunction | |
317 @end group | |
318 @end example | |
319 | |
320 In this particular case, the two values could have been returned as | |
321 elements of a single array, but that is not always possible or | |
322 convenient. The values to be returned may not have compatible | |
323 dimensions, and it is often desirable to give the individual return | |
324 values distinct names. | |
325 | |
13749
62d1f56b0be7
New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
12642
diff
changeset
|
326 It is possible to use the @code{nthargout} function to obtain only some |
14038
b0cdd60db5e5
doc: Grammarcheck documentation ahead of 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
13852
diff
changeset
|
327 of the return values or several at once in a cell array. |
17097
e7a059a9a644
doc: Use XREF as anchor prefix in documentation for clearer results in Info viewer.
Rik <rik@octave.org>
parents:
16772
diff
changeset
|
328 @xref{Cell Array Objects}. |
13749
62d1f56b0be7
New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
12642
diff
changeset
|
329 |
62d1f56b0be7
New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
12642
diff
changeset
|
330 @DOCSTRING(nthargout) |
62d1f56b0be7
New nthargout function
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
12642
diff
changeset
|
331 |
3294 | 332 In addition to setting @code{nargin} each time a function is called, |
333 Octave also automatically initializes @code{nargout} to the number of | |
334 values that are expected to be returned. This allows you to write | |
335 functions that behave differently depending on the number of values that | |
336 the user of the function has requested. The implicit assignment to the | |
337 built-in variable @code{ans} does not figure in the count of output | |
338 arguments, so the value of @code{nargout} may be zero. | |
339 | |
340 The @code{svd} and @code{lu} functions are examples of built-in | |
341 functions that behave differently depending on the value of | |
342 @code{nargout}. | |
343 | |
344 It is possible to write functions that only set some return values. For | |
345 example, calling the function | |
346 | |
347 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
348 @group |
3294 | 349 function [x, y, z] = f () |
350 x = 1; | |
351 z = 2; | |
352 endfunction | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
353 @end group |
3294 | 354 @end example |
355 | |
356 @noindent | |
357 as | |
358 | |
359 @example | |
360 [a, b, c] = f () | |
361 @end example | |
362 | |
363 @noindent | |
364 produces: | |
365 | |
366 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
367 @group |
3294 | 368 a = 1 |
369 | |
370 b = [](0x0) | |
371 | |
372 c = 2 | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
373 @end group |
3294 | 374 @end example |
375 | |
376 @noindent | |
6501 | 377 along with a warning. |
3294 | 378 |
4700 | 379 @DOCSTRING(nargout) |
3294 | 380 |
12629
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
381 It is good practice at the head of a function to verify that it has been called |
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
382 correctly. In Octave the following idiom is seen frequently |
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
383 |
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
384 @example |
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
385 @group |
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
386 if (nargin < min_#_inputs || nargin > max_#_inputs) |
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
387 print_usage (); |
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
388 endif |
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
389 @end group |
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
390 @end example |
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
391 |
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
392 @noindent |
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
393 which stops the function execution and prints a message about the correct |
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
394 way to call the function whenever the number of inputs is wrong. |
8c25df502846
func.txi: document use of nargin checking at head of function.
Rik <octave@nomad.inbox5.com>
parents:
12592
diff
changeset
|
395 |
19102
be8a12acb20a
Deprecate nargchk in favor of narginchk.
Rik <rik@octave.org>
parents:
19074
diff
changeset
|
396 For compatibility with @sc{matlab}, @code{narginchk} and @code{nargoutchk} are |
be8a12acb20a
Deprecate nargchk in favor of narginchk.
Rik <rik@octave.org>
parents:
19074
diff
changeset
|
397 available which provide similar error checking. |
3294 | 398 |
13852
e36817e2ee60
New function narginchk
Carnë Draug <carandraug+dev@gmail.com>
parents:
13749
diff
changeset
|
399 @DOCSTRING(narginchk) |
e36817e2ee60
New function narginchk
Carnë Draug <carandraug+dev@gmail.com>
parents:
13749
diff
changeset
|
400 |
7984
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
401 @DOCSTRING(nargoutchk) |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
402 |
19103
efd5cf93013b
doc: Move validatestrings into function chapter of manual.
Rik <rik@octave.org>
parents:
19102
diff
changeset
|
403 Besides the number of arguments, inputs can be checked for various properties. |
efd5cf93013b
doc: Move validatestrings into function chapter of manual.
Rik <rik@octave.org>
parents:
19102
diff
changeset
|
404 @code{validatestring} is used for string arguments and |
efd5cf93013b
doc: Move validatestrings into function chapter of manual.
Rik <rik@octave.org>
parents:
19102
diff
changeset
|
405 @code{validateattributes} for numeric arguments. |
efd5cf93013b
doc: Move validatestrings into function chapter of manual.
Rik <rik@octave.org>
parents:
19102
diff
changeset
|
406 |
efd5cf93013b
doc: Move validatestrings into function chapter of manual.
Rik <rik@octave.org>
parents:
19102
diff
changeset
|
407 @DOCSTRING(validatestring) |
efd5cf93013b
doc: Move validatestrings into function chapter of manual.
Rik <rik@octave.org>
parents:
19102
diff
changeset
|
408 |
efd5cf93013b
doc: Move validatestrings into function chapter of manual.
Rik <rik@octave.org>
parents:
19102
diff
changeset
|
409 @DOCSTRING(validateattributes) |
efd5cf93013b
doc: Move validatestrings into function chapter of manual.
Rik <rik@octave.org>
parents:
19102
diff
changeset
|
410 |
efd5cf93013b
doc: Move validatestrings into function chapter of manual.
Rik <rik@octave.org>
parents:
19102
diff
changeset
|
411 If none of the preceding functions is sufficient there is also the class |
efd5cf93013b
doc: Move validatestrings into function chapter of manual.
Rik <rik@octave.org>
parents:
19102
diff
changeset
|
412 @code{inputParser} which can perform extremely complex input checking for |
efd5cf93013b
doc: Move validatestrings into function chapter of manual.
Rik <rik@octave.org>
parents:
19102
diff
changeset
|
413 functions. |
19069
ff820f92cbb5
inputParser: classdef port of @inputParser from Octave Forge general pkg.
Carnë Draug <carandraug@octave.org>
parents:
18537
diff
changeset
|
414 |
ff820f92cbb5
inputParser: classdef port of @inputParser from Octave Forge general pkg.
Carnë Draug <carandraug@octave.org>
parents:
18537
diff
changeset
|
415 @DOCSTRING(inputParser) |
ff820f92cbb5
inputParser: classdef port of @inputParser from Octave Forge general pkg.
Carnë Draug <carandraug@octave.org>
parents:
18537
diff
changeset
|
416 |
17097
e7a059a9a644
doc: Use XREF as anchor prefix in documentation for clearer results in Info viewer.
Rik <rik@octave.org>
parents:
16772
diff
changeset
|
417 @anchor{XREFvarargin} @anchor{XREFvarargout} |
4167 | 418 @node Variable-length Argument Lists |
3294 | 419 @section Variable-length Argument Lists |
4933 | 420 @cindex variable-length argument lists |
8567 | 421 @cindex @code{varargin} |
8072 | 422 |
6510 | 423 Sometimes the number of input arguments is not known when the function |
424 is defined. As an example think of a function that returns the smallest | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
425 of all its input arguments. For example: |
6510 | 426 |
427 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
428 @group |
6510 | 429 a = smallest (1, 2, 3); |
430 b = smallest (1, 2, 3, 4); | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
431 @end group |
6510 | 432 @end example |
433 | |
434 @noindent | |
435 In this example both @code{a} and @code{b} would be 1. One way to write | |
436 the @code{smallest} function is | |
437 | |
438 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
439 @group |
6510 | 440 function val = smallest (arg1, arg2, arg3, arg4, arg5) |
441 @var{body} | |
442 endfunction | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
443 @end group |
6510 | 444 @end example |
445 | |
446 @noindent | |
447 and then use the value of @code{nargin} to determine which of the input | |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
448 arguments should be considered. The problem with this approach is |
6510 | 449 that it can only handle a limited number of input arguments. |
450 | |
7588
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
451 If the special parameter name @code{varargin} appears at the end of a |
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
452 function parameter list it indicates that the function takes a variable |
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
453 number of input arguments. Using @code{varargin} the function |
6510 | 454 looks like this |
455 | |
456 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
457 @group |
6510 | 458 function val = smallest (varargin) |
459 @var{body} | |
460 endfunction | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
461 @end group |
6510 | 462 @end example |
463 | |
464 @noindent | |
465 In the function body the input arguments can be accessed through the | |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
466 variable @code{varargin}. This variable is a cell array containing |
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
467 all the input arguments. @xref{Cell Arrays}, for details on working |
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
468 with cell arrays. The @code{smallest} function can now be defined |
6510 | 469 like this |
470 | |
471 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
472 @group |
6510 | 473 function val = smallest (varargin) |
474 val = min ([varargin@{:@}]); | |
475 endfunction | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
476 @end group |
6510 | 477 @end example |
478 | |
479 @noindent | |
480 This implementation handles any number of input arguments, but it's also | |
481 a very simple solution to the problem. | |
482 | |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18535
diff
changeset
|
483 A slightly more complex example of @code{varargin} is a function |
6510 | 484 @code{print_arguments} that prints all input arguments. Such a function |
485 can be defined like this | |
486 | |
487 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
488 @group |
6510 | 489 function print_arguments (varargin) |
490 for i = 1:length (varargin) | |
491 printf ("Input argument %d: ", i); | |
492 disp (varargin@{i@}); | |
493 endfor | |
494 endfunction | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
495 @end group |
6510 | 496 @end example |
497 | |
498 @noindent | |
499 This function produces output like this | |
500 | |
501 @example | |
502 @group | |
503 print_arguments (1, "two", 3); | |
504 @print{} Input argument 1: 1 | |
505 @print{} Input argument 2: two | |
506 @print{} Input argument 3: 3 | |
507 @end group | |
508 @end example | |
3294 | 509 |
6558 | 510 @DOCSTRING(parseparams) |
511 | |
10209
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
512 @node Ignoring Arguments |
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
513 @section Ignoring Arguments |
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
514 |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
515 In the formal argument list, it is possible to use the dummy placeholder |
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
516 @code{~} instead of a name. This indicates that the corresponding argument |
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
517 value should be ignored and not stored to any variable. |
10209
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
518 |
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
519 @example |
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
520 @group |
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
521 function val = pick2nd (~, arg2) |
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
522 val = arg2; |
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
523 endfunction |
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
524 @end group |
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
525 @end example |
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
526 |
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
527 The value of @code{nargin} is not affected by using this declaration. |
ea0d83b4470b
document use of ~ placeholders in the manual
Jaroslav Hajek <highegg@gmail.com>
parents:
9209
diff
changeset
|
528 |
12592
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
529 Return arguments can also be ignored using the same syntax. Functions may |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
530 take advantage of ignored outputs to reduce the number of calculations |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
531 performed. To do so, use the @code{isargout} function to query whether the |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
532 output argument is wanted. For example: |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
533 |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
534 @example |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
535 @group |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
536 function [out1, out2] = long_function (x, y, z) |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
537 if (isargout (1)) |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
538 ## Long calculation |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
539 @dots{} |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
540 out1 = result; |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
541 endif |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
542 @dots{} |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
543 endfunction |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
544 @end group |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
545 @end example |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
546 |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
547 @DOCSTRING(isargout) |
732a568bf694
Modify func.txi discussion of output arguments to include discussion of isargout.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
548 |
4167 | 549 @node Variable-length Return Lists |
3294 | 550 @section Variable-length Return Lists |
4933 | 551 @cindex variable-length return lists |
8567 | 552 @cindex @code{varargout} |
8072 | 553 |
6510 | 554 It is possible to return a variable number of output arguments from a |
555 function using a syntax that's similar to the one used with the | |
7588
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
556 special @code{varargin} parameter name. To let a function return a |
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
557 variable number of output arguments the special output parameter name |
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
558 @code{varargout} is used. As with @code{varargin}, @code{varargout} is |
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
559 a cell array that will contain the requested output arguments. |
6510 | 560 |
561 As an example the following function sets the first output argument to | |
562 1, the second to 2, and so on. | |
563 | |
564 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
565 @group |
6510 | 566 function varargout = one_to_n () |
567 for i = 1:nargout | |
568 varargout@{i@} = i; | |
569 endfor | |
570 endfunction | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
571 @end group |
6510 | 572 @end example |
573 | |
574 @noindent | |
575 When called this function returns values like this | |
576 | |
577 @example | |
578 @group | |
579 [a, b, c] = one_to_n () | |
580 @result{} a = 1 | |
581 @result{} b = 2 | |
582 @result{} c = 3 | |
583 @end group | |
584 @end example | |
3294 | 585 |
7588
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
586 If @code{varargin} (@code{varargout}) does not appear as the last |
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
587 element of the input (output) parameter list, then it is not special, |
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
588 and is handled the same as any other parameter name. |
cbedf652a752
doc fix for varargin and varargout change
John W. Eaton <jwe@octave.org>
parents:
7031
diff
changeset
|
589 |
6558 | 590 @DOCSTRING(deal) |
591 | |
11255
d682cd6669ac
Update info-based documentation menus to include new nodes.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
592 @node Returning from a Function |
d682cd6669ac
Update info-based documentation menus to include new nodes.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
593 @section Returning from a Function |
3294 | 594 |
595 The body of a user-defined function can contain a @code{return} statement. | |
596 This statement returns control to the rest of the Octave program. It | |
597 looks like this: | |
598 | |
599 @example | |
600 return | |
601 @end example | |
602 | |
603 Unlike the @code{return} statement in C, Octave's @code{return} | |
604 statement cannot be used to return a value from a function. Instead, | |
605 you must assign values to the list of return variables that are part of | |
606 the @code{function} statement. The @code{return} statement simply makes | |
607 it easier to exit a function from a deeply nested loop or conditional | |
608 statement. | |
609 | |
610 Here is an example of a function that checks to see if any elements of a | |
611 vector are nonzero. | |
612 | |
613 @example | |
614 @group | |
615 function retval = any_nonzero (v) | |
616 retval = 0; | |
617 for i = 1:length (v) | |
618 if (v (i) != 0) | |
619 retval = 1; | |
620 return; | |
621 endif | |
622 endfor | |
623 printf ("no nonzero elements found\n"); | |
624 endfunction | |
625 @end group | |
626 @end example | |
627 | |
628 Note that this function could not have been written using the | |
629 @code{break} statement to exit the loop once a nonzero value is found | |
630 without adding extra logic to avoid printing the message if the vector | |
631 does contain a nonzero element. | |
632 | |
11547 | 633 @deftypefn {Keyword} {} return |
3294 | 634 When Octave encounters the keyword @code{return} inside a function or |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
635 script, it returns control to the caller immediately. At the top level, |
3294 | 636 the return statement is ignored. A @code{return} statement is assumed |
637 at the end of every function definition. | |
11547 | 638 @end deftypefn |
3294 | 639 |
6510 | 640 @node Default Arguments |
641 @section Default Arguments | |
642 @cindex default arguments | |
643 | |
644 Since Octave supports variable number of input arguments, it is very useful | |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
645 to assign default values to some input arguments. When an input argument |
6510 | 646 is declared in the argument list it is possible to assign a default |
647 value to the argument like this | |
648 | |
649 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
650 @group |
6510 | 651 function @var{name} (@var{arg1} = @var{val1}, @dots{}) |
652 @var{body} | |
653 endfunction | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
654 @end group |
6510 | 655 @end example |
656 | |
657 @noindent | |
658 If no value is assigned to @var{arg1} by the user, it will have the | |
659 value @var{val1}. | |
660 | |
661 As an example, the following function implements a variant of the classic | |
662 ``Hello, World'' program. | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
663 |
6510 | 664 @example |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
665 @group |
6510 | 666 function hello (who = "World") |
667 printf ("Hello, %s!\n", who); | |
668 endfunction | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
669 @end group |
6510 | 670 @end example |
671 | |
672 @noindent | |
673 When called without an input argument the function prints the following | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
674 |
6510 | 675 @example |
676 @group | |
677 hello (); | |
678 @print{} Hello, World! | |
679 @end group | |
680 @end example | |
681 | |
682 @noindent | |
683 and when it's called with an input argument it prints the following | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
684 |
6510 | 685 @example |
686 @group | |
687 hello ("Beautiful World of Free Software"); | |
688 @print{} Hello, Beautiful World of Free Software! | |
689 @end group | |
690 @end example | |
691 | |
692 Sometimes it is useful to explicitly tell Octave to use the default value | |
693 of an input argument. This can be done writing a @samp{:} as the value | |
694 of the input argument when calling the function. | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
695 |
6510 | 696 @example |
697 @group | |
698 hello (:); | |
699 @print{} Hello, World! | |
700 @end group | |
701 @end example | |
702 | |
4167 | 703 @node Function Files |
3294 | 704 @section Function Files |
705 @cindex function file | |
706 | |
707 Except for simple one-shot programs, it is not practical to have to | |
708 define all the functions you need each time you need them. Instead, you | |
709 will normally want to save them in a file so that you can easily edit | |
710 them, and save them for use at a later time. | |
711 | |
712 Octave does not require you to load function definitions from files | |
713 before using them. You simply need to put the function definitions in a | |
714 place where Octave can find them. | |
715 | |
716 When Octave encounters an identifier that is undefined, it first looks | |
717 for variables or functions that are already compiled and currently | |
718 listed in its symbol table. If it fails to find a definition there, it | |
6556 | 719 searches a list of directories (the @dfn{path}) for files ending in |
6554 | 720 @file{.m} that have the same base name as the undefined |
721 identifier.@footnote{The @samp{.m} suffix was chosen for compatibility | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
722 with @sc{matlab}.} Once Octave finds a file with a name that matches, |
6554 | 723 the contents of the file are read. If it defines a @emph{single} |
724 function, it is compiled and executed. @xref{Script Files}, for more | |
725 information about how you can define more than one function in a single | |
726 file. | |
3294 | 727 |
728 When Octave defines a function from a function file, it saves the full | |
6554 | 729 name of the file it read and the time stamp on the file. If the time |
730 stamp on the file changes, Octave may reload the file. When Octave is | |
731 running interactively, time stamp checking normally happens at most once | |
732 each time Octave prints the prompt. Searching for new function | |
733 definitions also occurs if the current working directory changes. | |
3294 | 734 |
735 Checking the time stamp allows you to edit the definition of a function | |
736 while Octave is running, and automatically use the new function | |
6554 | 737 definition without having to restart your Octave session. |
3294 | 738 |
739 To avoid degrading performance unnecessarily by checking the time stamps | |
740 on functions that are not likely to change, Octave assumes that function | |
741 files in the directory tree | |
742 @file{@var{octave-home}/share/octave/@var{version}/m} | |
743 will not change, so it doesn't have to check their time stamps every time the | |
744 functions defined in those files are used. This is normally a very good | |
745 assumption and provides a significant improvement in performance for the | |
746 function files that are distributed with Octave. | |
747 | |
748 If you know that your own function files will not change while you are | |
6554 | 749 running Octave, you can improve performance by calling |
750 @code{ignore_function_time_stamp ("all")}, so that Octave will | |
751 ignore the time stamps for all function files. Passing | |
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
17152
diff
changeset
|
752 @qcode{"system"} to this function resets the default behavior. |
3294 | 753 |
5775 | 754 @c FIXME -- note about time stamps on files in NFS environments? |
3294 | 755 |
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8567
diff
changeset
|
756 @DOCSTRING(edit) |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8567
diff
changeset
|
757 |
6549 | 758 @DOCSTRING(mfilename) |
759 | |
6638 | 760 @DOCSTRING(ignore_function_time_stamp) |
761 | |
762 @menu | |
11255
d682cd6669ac
Update info-based documentation menus to include new nodes.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
763 * Manipulating the Load Path:: |
6638 | 764 * Subfunctions:: |
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
765 * Private Functions:: |
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
766 * Nested Functions:: |
6638 | 767 * Overloading and Autoloading:: |
768 * Function Locking:: | |
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
769 * Function Precedence:: |
6638 | 770 @end menu |
771 | |
11257
8d4c57258523
fix some menu problems in the manual
John W. Eaton <jwe@octave.org>
parents:
11255
diff
changeset
|
772 @node Manipulating the Load Path |
8d4c57258523
fix some menu problems in the manual
John W. Eaton <jwe@octave.org>
parents:
11255
diff
changeset
|
773 @subsection Manipulating the Load Path |
6638 | 774 |
8828 | 775 When a function is called, Octave searches a list of directories for |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
776 a file that contains the function declaration. This list of directories |
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
777 is known as the load path. By default the load path contains |
6638 | 778 a list of directories distributed with Octave plus the current |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
779 working directory. To see your current load path call the @code{path} |
6638 | 780 function without any input or output arguments. |
781 | |
782 It is possible to add or remove directories to or from the load path | |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
783 using @code{addpath} and @code{rmpath}. As an example, the following |
6638 | 784 code adds @samp{~/Octave} to the load path. |
785 | |
786 @example | |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14851
diff
changeset
|
787 addpath ("~/Octave") |
6638 | 788 @end example |
789 | |
790 @noindent | |
791 After this the directory @samp{~/Octave} will be searched for functions. | |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18535
diff
changeset
|
792 |
6502 | 793 @DOCSTRING(addpath) |
794 | |
795 @DOCSTRING(genpath) | |
796 | |
797 @DOCSTRING(rmpath) | |
798 | |
799 @DOCSTRING(savepath) | |
800 | |
6477 | 801 @DOCSTRING(path) |
3294 | 802 |
6502 | 803 @DOCSTRING(pathdef) |
804 | |
805 @DOCSTRING(pathsep) | |
806 | |
3428 | 807 @DOCSTRING(rehash) |
808 | |
809 @DOCSTRING(file_in_loadpath) | |
810 | |
7638
2df457529cfa
implement expm1 and log1p functions
Jaroslav Hajek <highegg@gmail.com>
parents:
7588
diff
changeset
|
811 @DOCSTRING(restoredefaultpath) |
2df457529cfa
implement expm1 and log1p functions
Jaroslav Hajek <highegg@gmail.com>
parents:
7588
diff
changeset
|
812 |
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8567
diff
changeset
|
813 @DOCSTRING(command_line_path) |
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8567
diff
changeset
|
814 |
18109
2217bc116aa9
maint: Dummy merge with gui-release, ignoring all recent backout merges
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
18104
diff
changeset
|
815 @DOCSTRING(dir_in_loadpath) |
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8567
diff
changeset
|
816 |
6556 | 817 @node Subfunctions |
818 @subsection Subfunctions | |
819 | |
820 A function file may contain secondary functions called | |
821 @dfn{subfunctions}. These secondary functions are only visible to the | |
822 other functions in the same function file. For example, a file | |
823 @file{f.m} containing | |
824 | |
825 @example | |
826 @group | |
827 function f () | |
828 printf ("in f, calling g\n"); | |
829 g () | |
830 endfunction | |
831 function g () | |
832 printf ("in g, calling h\n"); | |
6638 | 833 h () |
6556 | 834 endfunction |
835 function h () | |
836 printf ("in h\n") | |
837 endfunction | |
838 @end group | |
839 @end example | |
840 | |
841 @noindent | |
842 defines a main function @code{f} and two subfunctions. The | |
843 subfunctions @code{g} and @code{h} may only be called from the main | |
844 function @code{f} or from the other subfunctions, but not from outside | |
845 the file @file{f.m}. | |
846 | |
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
847 @node Private Functions |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
848 @subsection Private Functions |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
849 |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
850 In many cases one function needs to access one or more helper |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
851 functions. If the helper function is limited to the scope of a single |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
852 function, then subfunctions as discussed above might be used. However, |
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
853 if a single helper function is used by more than one function, then |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
854 this is no longer possible. In this case the helper functions might |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
855 be placed in a subdirectory, called "private", of the directory in which |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
856 the functions needing access to this helper function are found. |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
857 |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
858 As a simple example, consider a function @code{func1}, that calls a helper |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
859 function @code{func2} to do much of the work. For example: |
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
860 |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
861 @example |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
862 @group |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
863 function y = func1 (x) |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
864 y = func2 (x); |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
865 endfunction |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
866 @end group |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
867 @end example |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
868 |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
869 @noindent |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
870 Then if the path to @code{func1} is @code{<directory>/func1.m}, and if |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18535
diff
changeset
|
871 @code{func2} is found in the directory @code{<directory>/private/func2.m}, |
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18535
diff
changeset
|
872 then @code{func2} is only available for use of the functions, like |
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
873 @code{func1}, that are found in @code{<directory>}. |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
874 |
14851
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
875 @node Nested Functions |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
876 @subsection Nested Functions |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
877 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
878 Nested functions are similar to subfunctions in that only the main function is |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
879 visible outside the file. However, they also allow for child functions to |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
880 access the local variables in their parent function. This shared access mimics |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
881 using a global variable to share information --- but a global variable which is |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
882 not visible to the rest of Octave. As a programming strategy, sharing data |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
883 this way can create code which is difficult to maintain. It is recommended to |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
884 use subfunctions in place of nested functions when possible. |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
885 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
886 As a simple example, consider a parent function @code{foo}, that calls a nested |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
887 child function @code{bar}, with a shared variable @var{x}. |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
888 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
889 @example |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
890 @group |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
891 function y = foo () |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
892 x = 10; |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
893 bar (); |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
894 y = x; |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
895 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
896 function bar () |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
897 x = 20; |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
898 endfunction |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
899 endfunction |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
900 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
901 foo () |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
902 @result{} 20 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
903 @end group |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
904 @end example |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
905 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
906 @noindent |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
907 Notice that there is no special syntax for sharing @var{x}. This can lead to |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
908 problems with accidental variable sharing between a parent function and its |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
909 child. While normally variables are inherited, child function parameters and |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
910 return values are local to the child function. |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
911 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
912 Now consider the function @code{foobar} that uses variables @var{x} and |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
913 @var{y}. @code{foobar} calls a nested function @code{foo} which takes |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
914 @var{x} as a parameter and returns @var{y}. @code{foo} then calls @code{bat} |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
915 which does some computation. |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
916 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
917 @example |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
918 @group |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
919 function z = foobar () |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
920 x = 0; |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
921 y = 0; |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
922 z = foo (5); |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
923 z += x + y; |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
924 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
925 function y = foo (x) |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
926 y = x + bat (); |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
927 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
928 function z = bat () |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
929 z = x; |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
930 endfunction |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
931 endfunction |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
932 endfunction |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
933 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
934 foobar () |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
935 @result{} 10 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
936 @end group |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
937 @end example |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
938 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
939 @noindent |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
940 It is important to note that the @var{x} and @var{y} in @code{foobar} remain |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
941 zero, as in @code{foo} they are a return value and parameter respectively. The |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
942 @var{x} in @code{bat} refers to the @var{x} in @code{foo}. |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
943 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
944 Variable inheritance leads to a problem for @code{eval} and scripts. If a |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
945 new variable is created in a parent function, it is not clear what should happen |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
946 in nested child functions. For example, consider a parent function @code{foo} |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
947 with a nested child function @code{bar}: |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
948 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
949 @example |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
950 @group |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
951 function y = foo (to_eval) |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
952 bar (); |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
953 eval (to_eval); |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
954 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
955 function bar () |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
956 eval ("x = 100;"); |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
957 eval ("y = x;"); |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
958 endfunction |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
959 endfunction |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
960 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
961 foo ("x = 5;") |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
962 @result{} error: can not add variable "x" to a static workspace |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
963 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
964 foo ("y = 10;") |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
965 @result{} 10 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
966 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
967 foo ("") |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
968 @result{} 100 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
969 @end group |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
970 @end example |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
971 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
972 @noindent |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
973 The parent function @code{foo} is unable to create a new variable |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
974 @var{x}, but the child function @code{bar} was successful. Furthermore, even |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
975 in an @code{eval} statement @var{y} in @code{bar} is the same @var{y} as in its |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
976 parent function @code{foo}. The use of @code{eval} in conjunction with nested |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
977 functions is best avoided. |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
978 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
979 As with subfunctions, only the first nested function in a file may be called |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
980 from the outside. Inside a function the rules are more complicated. In |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
981 general a nested function may call: |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
982 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
983 @enumerate 0 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
984 @item |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
985 Globally visible functions |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
986 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
987 @item |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
988 Any function that the nested function's parent can call |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
989 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
990 @item |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
991 Sibling functions (functions that have the same parents) |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
992 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
993 @item |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
994 Direct children |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
995 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
996 @end enumerate |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
997 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
998 As a complex example consider a parent function @code{ex_top} with two |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
999 child functions, @code{ex_a} and @code{ex_b}. In addition, @code{ex_a} has two |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1000 more child functions, @code{ex_aa} and @code{ex_ab}. For example: |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1001 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1002 @example |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1003 function ex_top () |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1004 ## Can call: ex_top, ex_a, and ex_b |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1005 ## Can NOT call: ex_aa and ex_ab |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1006 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1007 function ex_a () |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1008 ## Call call everything |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1009 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1010 function ex_aa () |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1011 ## Can call everything |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1012 endfunction |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1013 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1014 function ex_ab () |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1015 ## Can call everything |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1016 endfunction |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1017 endfunction |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1018 |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1019 function ex_b () |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1020 ## Can call: ex_top, ex_a, and ex_b |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1021 ## Can NOT call: ex_aa and ex_ab |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1022 endfunction |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1023 endfunction |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1024 @end example |
fa3989fbb1b5
doc: Add subchapter on nested functions (bug #36147)
Max Brister <max@2bass.com>
parents:
14846
diff
changeset
|
1025 |
6635 | 1026 @node Overloading and Autoloading |
1027 @subsection Overloading and Autoloading | |
1028 | |
11396
7b563cf94d8d
Remove documentation on deprecated function dispatch
Rik <octave@nomad.inbox5.com>
parents:
11392
diff
changeset
|
1029 Functions can be overloaded to work with different input arguments. For |
7b563cf94d8d
Remove documentation on deprecated function dispatch
Rik <octave@nomad.inbox5.com>
parents:
11392
diff
changeset
|
1030 example, the operator '+' has been overloaded in Octave to work with single, |
7b563cf94d8d
Remove documentation on deprecated function dispatch
Rik <octave@nomad.inbox5.com>
parents:
11392
diff
changeset
|
1031 double, uint8, int32, and many other arguments. The preferred way to overload |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18535
diff
changeset
|
1032 functions is through classes and object oriented programming |
11396
7b563cf94d8d
Remove documentation on deprecated function dispatch
Rik <octave@nomad.inbox5.com>
parents:
11392
diff
changeset
|
1033 (@pxref{Function Overloading}). Occasionally, however, one needs to undo |
7b563cf94d8d
Remove documentation on deprecated function dispatch
Rik <octave@nomad.inbox5.com>
parents:
11392
diff
changeset
|
1034 user overloading and call the default function associated with a specific |
7b563cf94d8d
Remove documentation on deprecated function dispatch
Rik <octave@nomad.inbox5.com>
parents:
11392
diff
changeset
|
1035 type. The @code{builtin} function exists for this purpose. |
6635 | 1036 |
1037 @DOCSTRING(builtin) | |
1038 | |
1039 A single dynamically linked file might define several | |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1040 functions. However, as Octave searches for functions based on the |
6635 | 1041 functions filename, Octave needs a manner in which to find each of the |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1042 functions in the dynamically linked file. On operating systems that |
6635 | 1043 support symbolic links, it is possible to create a symbolic link to the |
1044 original file for each of the functions which it contains. | |
1045 | |
1046 However, there is at least one well known operating system that doesn't | |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1047 support symbolic links. Making copies of the original file for each of |
8828 | 1048 the functions is undesirable as it increases the |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1049 amount of disk space used by Octave. Instead Octave supplies the |
6635 | 1050 @code{autoload} function, that permits the user to define in which |
1051 file a certain function will be found. | |
1052 | |
1053 @DOCSTRING(autoload) | |
1054 | |
1055 @node Function Locking | |
1056 @subsection Function Locking | |
1057 | |
1058 It is sometime desirable to lock a function into memory with the | |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1059 @code{mlock} function. This is typically used for dynamically linked |
6899 | 1060 functions in Oct-files or mex-files that contain some initialization, |
1061 and it is desirable that calling @code{clear} does not remove this | |
6635 | 1062 initialization. |
1063 | |
6899 | 1064 As an example, |
1065 | |
1066 @example | |
18491
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1067 @group |
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1068 function my_function () |
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1069 mlock (); |
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1070 @dots{} |
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1071 @end group |
6899 | 1072 @end example |
1073 | |
1074 @noindent | |
18491
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1075 prevents @code{my_function} from being removed from memory after it is |
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1076 called, even if @code{clear} is called. It is possible to determine if |
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1077 a function is locked into memory with the @code{mislocked}, and to unlock |
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1078 a function with @code{munlock}, which the following illustrates. |
6899 | 1079 |
1080 @example | |
1081 @group | |
18491
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1082 my_function (); |
6899 | 1083 mislocked ("my_function") |
1084 @result{} ans = 1 | |
1085 munlock ("my_function"); | |
1086 mislocked ("my_function") | |
1087 @result{} ans = 0 | |
1088 @end group | |
1089 @end example | |
1090 | |
1091 A common use of @code{mlock} is to prevent persistent variables from | |
8828 | 1092 being removed from memory, as the following example shows: |
6899 | 1093 |
1094 @example | |
1095 @group | |
14846
460a3c6d8bf1
maint: Use Octave coding convention for cuddled parenthis in function calls with empty argument lists.
Rik <octave@nomad.inbox5.com>
parents:
14442
diff
changeset
|
1096 function count_calls () |
18491
477b5916cafe
doc: Update function locking section with correct usage of mlock (bug #41627)
Mike Miller <mtmiller@ieee.org>
parents:
17744
diff
changeset
|
1097 mlock (); |
6899 | 1098 persistent calls = 0; |
7031 | 1099 printf ("'count_calls' has been called %d times\n", |
1100 ++calls); | |
6899 | 1101 endfunction |
1102 | |
1103 count_calls (); | |
1104 @print{} 'count_calls' has been called 1 times | |
1105 | |
1106 clear count_calls | |
1107 count_calls (); | |
1108 @print{} 'count_calls' has been called 2 times | |
1109 @end group | |
1110 @end example | |
1111 | |
1112 @code{mlock} might equally be used to prevent changes to a function from having | |
6635 | 1113 effect in Octave, though a similar effect can be had with the |
1114 @code{ignore_function_time_stamp} function. | |
1115 | |
1116 @DOCSTRING(mlock) | |
1117 | |
1118 @DOCSTRING(munlock) | |
1119 | |
1120 @DOCSTRING(mislocked) | |
1121 | |
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1122 @node Function Precedence |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1123 @subsection Function Precedence |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1124 |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1125 Given the numerous different ways that Octave can define a function, it |
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1126 is possible and even likely that multiple versions of a function, might be |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1127 defined within a particular scope. The precedence of which function will be |
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1128 used within a particular scope is given by |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1129 |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1130 @enumerate 1 |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1131 @item Subfunction |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1132 A subfunction with the required function name in the given scope. |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1133 |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1134 @item Private function |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18535
diff
changeset
|
1135 A function defined within a private directory of the directory |
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1136 which contains the current function. |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1137 |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1138 @item Class constructor |
19074
0850b5212619
doc: Add @nospell macro around proper names in documentation.
Rik <rik@octave.org>
parents:
19069
diff
changeset
|
1139 A function that constructs a user class as defined in chapter |
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1140 @ref{Object Oriented Programming}. |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1141 |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1142 @item Class method |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1143 An overloaded function of a class as in chapter |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1144 @ref{Object Oriented Programming}. |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1145 |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1146 @item Command-line Function |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1147 A function that has been defined on the command-line. |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1148 |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1149 @item Autoload function |
17097
e7a059a9a644
doc: Use XREF as anchor prefix in documentation for clearer results in Info viewer.
Rik <rik@octave.org>
parents:
16772
diff
changeset
|
1150 A function that is marked as autoloaded with @xref{XREFautoload,,autoload}. |
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1151 |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1152 @item A Function on the Path |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1153 A function that can be found on the users load-path. There can also be |
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1154 Oct-file, mex-file or m-file versions of this function and the precedence |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1155 between these versions are in that order. |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1156 |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1157 @item Built-in function |
18534
f51c1498b9f3
doc: Replace "builtin" with "built-in" for consistency and correctness.
Rik <rik@octave.org>
parents:
18491
diff
changeset
|
1158 A function that is a part of core Octave such as @code{numel}, @code{size}, |
f51c1498b9f3
doc: Replace "builtin" with "built-in" for consistency and correctness.
Rik <rik@octave.org>
parents:
18491
diff
changeset
|
1159 etc. |
8221
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1160 @end enumerate |
06094fa570a3
Add some documentation for the OOP code of Octave
David Bateman <dbateman@free.fr>
parents:
8074
diff
changeset
|
1161 |
4167 | 1162 @node Script Files |
3294 | 1163 @section Script Files |
1164 | |
1165 A script file is a file containing (almost) any sequence of Octave | |
1166 commands. It is read and evaluated just as if you had typed each | |
1167 command at the Octave prompt, and provides a convenient way to perform a | |
1168 sequence of commands that do not logically belong inside a function. | |
1169 | |
1170 Unlike a function file, a script file must @emph{not} begin with the | |
1171 keyword @code{function}. If it does, Octave will assume that it is a | |
1172 function file, and that it defines a single function that should be | |
1173 evaluated as soon as it is defined. | |
1174 | |
1175 A script file also differs from a function file in that the variables | |
1176 named in a script file are not local variables, but are in the same | |
1177 scope as the other variables that are visible on the command line. | |
1178 | |
1179 Even though a script file may not begin with the @code{function} | |
1180 keyword, it is possible to define more than one function in a single | |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18535
diff
changeset
|
1181 script file and load (but not execute) all of them at once. To do |
3294 | 1182 this, the first token in the file (ignoring comments and other white |
1183 space) must be something other than @code{function}. If you have no | |
1184 other statements to evaluate, you can use a statement that has no | |
1185 effect, like this: | |
1186 | |
1187 @example | |
1188 @group | |
1189 # Prevent Octave from thinking that this | |
1190 # is a function file: | |
1191 | |
1192 1; | |
1193 | |
1194 # Define function one: | |
1195 | |
1196 function one () | |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1197 @dots{} |
3294 | 1198 @end group |
1199 @end example | |
1200 | |
1201 To have Octave read and compile these functions into an internal form, | |
6638 | 1202 you need to make sure that the file is in Octave's load path |
6477 | 1203 (accessible through the @code{path} function), then simply type the |
1204 base name of the file that contains the commands. (Octave uses the | |
1205 same rules to search for script files as it does to search for | |
1206 function files.) | |
3294 | 1207 |
1208 If the first token in a file (ignoring comments) is @code{function}, | |
1209 Octave will compile the function and try to execute it, printing a | |
1210 message warning about any non-whitespace characters that appear after | |
1211 the function definition. | |
1212 | |
1213 Note that Octave does not try to look up the definition of any identifier | |
1214 until it needs to evaluate it. This means that Octave will compile the | |
1215 following statements if they appear in a script file, or are typed at | |
1216 the command line, | |
1217 | |
1218 @example | |
1219 @group | |
1220 # not a function file: | |
1221 1; | |
1222 function foo () | |
1223 do_something (); | |
1224 endfunction | |
1225 function do_something () | |
1226 do_something_else (); | |
1227 endfunction | |
1228 @end group | |
1229 @end example | |
1230 | |
1231 @noindent | |
1232 even though the function @code{do_something} is not defined before it is | |
1233 referenced in the function @code{foo}. This is not an error because | |
1234 Octave does not need to resolve all symbols that are referenced by a | |
1235 function until the function is actually evaluated. | |
1236 | |
1237 Since Octave doesn't look for definitions until they are needed, the | |
1238 following code will always print @samp{bar = 3} whether it is typed | |
1239 directly on the command line, read from a script file, or is part of a | |
1240 function body, even if there is a function or script file called | |
6477 | 1241 @file{bar.m} in Octave's path. |
3294 | 1242 |
1243 @example | |
1244 @group | |
1245 eval ("bar = 3"); | |
1246 bar | |
1247 @end group | |
1248 @end example | |
1249 | |
1250 Code like this appearing within a function body could fool Octave if | |
1251 definitions were resolved as the function was being compiled. It would | |
1252 be virtually impossible to make Octave clever enough to evaluate this | |
1253 code in a consistent fashion. The parser would have to be able to | |
1254 perform the call to @code{eval} at compile time, and that would be | |
1255 impossible unless all the references in the string to be evaluated could | |
1256 also be resolved, and requiring that would be too restrictive (the | |
1257 string might come from user input, or depend on things that are not | |
1258 known until the function is evaluated). | |
1259 | |
1260 Although Octave normally executes commands from script files that have | |
1261 the name @file{@var{file}.m}, you can use the function @code{source} to | |
1262 execute commands from any file. | |
1263 | |
3371 | 1264 @DOCSTRING(source) |
3294 | 1265 |
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
1266 @node Function Handles Anonymous Functions Inline Functions |
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
1267 @section Function Handles, Anonymous Functions, Inline Functions |
4933 | 1268 @cindex handle, function handles |
17152
f2a8592b8fbd
doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents:
17097
diff
changeset
|
1269 @cindex anonymous functions |
4933 | 1270 @cindex inline, inline functions |
1271 | |
6638 | 1272 It can be very convenient store a function in a variable so that it |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1273 can be passed to a different function. For example, a function that |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18535
diff
changeset
|
1274 performs numerical minimization needs access to the function that |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1275 should be minimized. |
4933 | 1276 |
1277 @menu | |
1278 * Function Handles:: | |
6554 | 1279 * Anonymous Functions:: |
4933 | 1280 * Inline Functions:: |
1281 @end menu | |
1282 | |
1283 @node Function Handles | |
1284 @subsection Function Handles | |
1285 | |
6554 | 1286 A function handle is a pointer to another function and is defined with |
1287 the syntax | |
1288 | |
1289 @example | |
1290 @@@var{function-name} | |
1291 @end example | |
1292 | |
1293 @noindent | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
1294 For example, |
6554 | 1295 |
1296 @example | |
6556 | 1297 f = @@sin; |
6554 | 1298 @end example |
1299 | |
1300 @noindent | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
1301 creates a function handle called @code{f} that refers to the |
6554 | 1302 function @code{sin}. |
1303 | |
1304 Function handles are used to call other functions indirectly, or to pass | |
1305 a function as an argument to another function like @code{quad} or | |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
1306 @code{fsolve}. For example: |
6554 | 1307 |
1308 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1309 @group |
6556 | 1310 f = @@sin; |
6554 | 1311 quad (f, 0, pi) |
6929 | 1312 @result{} 2 |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1313 @end group |
6554 | 1314 @end example |
1315 | |
1316 You may use @code{feval} to call a function using function handle, or | |
6570 | 1317 simply write the name of the function handle followed by an argument |
6554 | 1318 list. If there are no arguments, you must use an empty argument list |
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10711
diff
changeset
|
1319 @samp{()}. For example: |
6554 | 1320 |
1321 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1322 @group |
6556 | 1323 f = @@sin; |
6554 | 1324 feval (f, pi/4) |
6570 | 1325 @result{} 0.70711 |
6554 | 1326 f (pi/4) |
6570 | 1327 @result{} 0.70711 |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1328 @end group |
6554 | 1329 @end example |
1330 | |
14175
3972c4caa60a
Add new function is_function_handle (patch #7695)
Juan Pablo Carbajal <carbajal@ifi.uzh.ch>
parents:
14138
diff
changeset
|
1331 @DOCSTRING(is_function_handle) |
3972c4caa60a
Add new function is_function_handle (patch #7695)
Juan Pablo Carbajal <carbajal@ifi.uzh.ch>
parents:
14138
diff
changeset
|
1332 |
4933 | 1333 @DOCSTRING(functions) |
1334 | |
1335 @DOCSTRING(func2str) | |
1336 | |
1337 @DOCSTRING(str2func) | |
1338 | |
6570 | 1339 @node Anonymous Functions |
6554 | 1340 @subsection Anonymous Functions |
1341 | |
1342 Anonymous functions are defined using the syntax | |
1343 | |
1344 @example | |
1345 @@(@var{argument-list}) @var{expression} | |
1346 @end example | |
1347 | |
1348 @noindent | |
1349 Any variables that are not found in the argument list are inherited from | |
1350 the enclosing scope. Anonymous functions are useful for creating simple | |
1351 unnamed functions from expressions or for wrapping calls to other | |
1352 functions to adapt them for use by functions like @code{quad}. For | |
1353 example, | |
1354 | |
1355 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1356 @group |
6554 | 1357 f = @@(x) x.^2; |
1358 quad (f, 0, 10) | |
6570 | 1359 @result{} 333.33 |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1360 @end group |
6554 | 1361 @end example |
1362 | |
1363 @noindent | |
1364 creates a simple unnamed function from the expression @code{x.^2} and | |
1365 passes it to @code{quad}, | |
1366 | |
1367 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1368 @group |
6554 | 1369 quad (@@(x) sin (x), 0, pi) |
6933 | 1370 @result{} 2 |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1371 @end group |
6554 | 1372 @end example |
1373 | |
1374 @noindent | |
1375 wraps another function, and | |
1376 | |
1377 @example | |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1378 @group |
6554 | 1379 a = 1; |
1380 b = 2; | |
1381 quad (@@(x) betainc (x, a, b), 0, 0.4) | |
6929 | 1382 @result{} 0.13867 |
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1383 @end group |
6554 | 1384 @end example |
1385 | |
1386 @noindent | |
1387 adapts a function with several parameters to the form required by | |
1388 @code{quad}. In this example, the values of @var{a} and @var{b} that | |
1389 are passed to @code{betainc} are inherited from the current | |
1390 environment. | |
1391 | |
19469
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1392 Note that for performance reasons it is better to use handles to existing |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1393 Octave functions, rather than to define anonymous functions which wrap an |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1394 existing function. The integration of @code{sin (x)} is 5X faster if the code |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1395 is written as |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1396 |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1397 @example |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1398 quad (@@sin, 0, pi) |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1399 @end example |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1400 |
19610
e97c63531e76
doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents:
19469
diff
changeset
|
1401 @noindent |
19469
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1402 rather than using the anonymous function @code{@@(x) sin (x)}. There are many |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1403 operators which have functional equivalents that may be better choices than an |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1404 anonymous function. Instead of writing |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1405 |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1406 @example |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1407 f = @@(x, y) x + y |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1408 @end example |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1409 |
19610
e97c63531e76
doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents:
19469
diff
changeset
|
1410 @noindent |
19469
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1411 this should be coded as |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1412 |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1413 @example |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1414 f = @@plus |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1415 @end example |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1416 |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1417 @xref{Operator Overloading}, for a list of operators which also have a |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1418 functional form. |
51a1d1164449
Add extra docs about the performance benefits of operator functions (bug #36439).
Rik <rik@octave.org>
parents:
19186
diff
changeset
|
1419 |
4933 | 1420 @node Inline Functions |
1421 @subsection Inline Functions | |
1422 | |
6638 | 1423 An inline function is created from a string containing the function |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1424 body using the @code{inline} function. The following code defines the |
6638 | 1425 function @math{f(x) = x^2 + 2}. |
1426 | |
1427 @example | |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14851
diff
changeset
|
1428 f = inline ("x^2 + 2"); |
6638 | 1429 @end example |
1430 | |
1431 @noindent | |
1432 After this it is possible to evaluate @math{f} at any @math{x} by | |
1433 writing @code{f(x)}. | |
1434 | |
19156
c43223245085
doc: Add warnings about eventual removal of inline functions.
Rik <rik@octave.org>
parents:
19146
diff
changeset
|
1435 @strong{Caution}: @sc{matlab} has begun the process of deprecating inline |
c43223245085
doc: Add warnings about eventual removal of inline functions.
Rik <rik@octave.org>
parents:
19146
diff
changeset
|
1436 functions. At some point in the future support will be dropped and eventually |
19186
0f9c5a15c8fa
doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents:
19156
diff
changeset
|
1437 Octave will follow @sc{matlab} and also remove inline functions. Use anonymous |
0f9c5a15c8fa
doc: Periodic grammarcheck of documentation.
Rik <rik@octave.org>
parents:
19156
diff
changeset
|
1438 functions in all new code. |
19156
c43223245085
doc: Add warnings about eventual removal of inline functions.
Rik <rik@octave.org>
parents:
19146
diff
changeset
|
1439 |
4933 | 1440 @DOCSTRING(inline) |
1441 | |
1442 @DOCSTRING(argnames) | |
1443 | |
1444 @DOCSTRING(formula) | |
1445 | |
7984
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
1446 @DOCSTRING(symvar) |
bbaa5d7d0143
Some documentation updates
David Bateman <dbateman@free.fr>
parents:
7638
diff
changeset
|
1447 |
6549 | 1448 @node Commands |
1449 @section Commands | |
1450 | |
6638 | 1451 Commands are a special class of functions that only accept string |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1452 input arguments. A command can be called as an ordinary function, but |
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1453 it can also be called without the parentheses. For example, |
6638 | 1454 |
1455 @example | |
1456 my_command hello world | |
1457 @end example | |
1458 | |
1459 @noindent | |
19627
446c46af4b42
strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents:
18535
diff
changeset
|
1460 is equivalent to |
6638 | 1461 |
1462 @example | |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14851
diff
changeset
|
1463 my_command ("hello", "world") |
6638 | 1464 @end example |
1465 | |
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1466 @noindent |
6638 | 1467 The general form of a command call is |
1468 | |
1469 @example | |
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1470 @var{cmdname} @var{arg1} @var{arg2} @dots{} |
6638 | 1471 @end example |
1472 | |
1473 @noindent | |
1474 which translates directly to | |
1475 | |
1476 @example | |
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1477 @var{cmdname} ("@var{arg1}", "@var{arg2}", @dots{}) |
6638 | 1478 @end example |
1479 | |
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1480 Any regular function can be used as a command if it accepts string input |
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1481 arguments. For example: |
11573
6f8ffe2c6f76
Grammarcheck txi files for 3.4 release.
Rik <octave@nomad.inbox5.com>
parents:
11547
diff
changeset
|
1482 |
6638 | 1483 @example |
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1484 @group |
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1485 toupper lower_case_arg |
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1486 @result{} ans = LOWER_CASE_ARG |
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1487 @end group |
6638 | 1488 @end example |
1489 | |
1490 One difficulty of commands occurs when one of the string input arguments | |
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1491 is stored in a variable. Because Octave can't tell the difference between |
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1492 a variable name and an ordinary string, it is not possible to pass a |
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
9032
diff
changeset
|
1493 variable as input to a command. In such a situation a command must be |
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1494 called as a function. For example: |
6549 | 1495 |
11392
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1496 @example |
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1497 @group |
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1498 strvar = "hello world"; |
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1499 toupper strvar |
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1500 @result{} ans = STRVAR |
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1501 toupper (strvar) |
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1502 @result{} ans = HELLO WORLD |
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1503 @end group |
757efa1d7e2a
Remove deprecated functions from manual.
Rik <octave@nomad.inbox5.com>
parents:
11257
diff
changeset
|
1504 @end example |
6549 | 1505 |
1506 | |
4167 | 1507 @node Organization of Functions |
3294 | 1508 @section Organization of Functions Distributed with Octave |
1509 | |
1510 Many of Octave's standard functions are distributed as function files. | |
1511 They are loosely organized by topic, in subdirectories of | |
1512 @file{@var{octave-home}/lib/octave/@var{version}/m}, to make it easier | |
1513 to find them. | |
1514 | |
1515 The following is a list of all the function file subdirectories, and the | |
1516 types of functions you will find there. | |
1517 | |
1518 @table @file | |
1519 @item audio | |
1520 Functions for playing and recording sounds. | |
1521 | |
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1522 @item deprecated |
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1523 Out-of-date functions which will eventually be removed from Octave. |
3294 | 1524 |
1525 @item elfun | |
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1526 Elementary functions, principally trigonometric. |
3294 | 1527 |
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1528 @item @@ftp |
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1529 Class functions for the FTP object. |
6554 | 1530 |
3294 | 1531 @item general |
1532 Miscellaneous matrix manipulations, like @code{flipud}, @code{rot90}, | |
1533 and @code{triu}, as well as other basic functions, like | |
19146
bc640d4678fb
Undeprecate nargchk, but add note that narginchk is preferred.
Rik <rik@octave.org>
parents:
19103
diff
changeset
|
1534 @code{ismatrix}, @code{narginchk}, etc. |
3294 | 1535 |
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1536 @item geometry |
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1537 Functions related to Delaunay triangulation. |
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1538 |
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1539 @item help |
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1540 Functions for Octave's built-in help system. |
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1541 |
3294 | 1542 @item image |
1543 Image processing tools. These functions require the X Window System. | |
1544 | |
1545 @item io | |
8325
b93ac0586e4b
spelling corrections
Brian Gough<bjg@network-theory.co.uk>
parents:
8286
diff
changeset
|
1546 Input-output functions. |
3294 | 1547 |
1548 @item linear-algebra | |
1549 Functions for linear algebra. | |
1550 | |
1551 @item miscellaneous | |
1552 Functions that don't really belong anywhere else. | |
1553 | |
6554 | 1554 @item optimization |
12642
f96b9b9f141b
doc: Periodic grammarcheck and spellcheck of documentation.
Rik <octave@nomad.inbox5.com>
parents:
12632
diff
changeset
|
1555 Functions related to minimization, optimization, and root finding. |
6554 | 1556 |
1557 @item path | |
1558 Functions to manage the directory path Octave uses to find functions. | |
1559 | |
1560 @item pkg | |
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1561 Package manager for installing external packages of functions in Octave. |
6554 | 1562 |
3294 | 1563 @item plot |
6556 | 1564 Functions for displaying and printing two- and three-dimensional graphs. |
3294 | 1565 |
1566 @item polynomial | |
1567 Functions for manipulating polynomials. | |
1568 | |
14133
b25559bd5aaa
doc: Document prefs directory in list of installed script files.
Rik <octave@nomad.inbox5.com>
parents:
14116
diff
changeset
|
1569 @item prefs |
b25559bd5aaa
doc: Document prefs directory in list of installed script files.
Rik <octave@nomad.inbox5.com>
parents:
14116
diff
changeset
|
1570 Functions implementing user-defined preferences. |
b25559bd5aaa
doc: Document prefs directory in list of installed script files.
Rik <octave@nomad.inbox5.com>
parents:
14116
diff
changeset
|
1571 |
3294 | 1572 @item set |
1573 Functions for creating and manipulating sets of unique values. | |
1574 | |
1575 @item signal | |
1576 Functions for signal processing applications. | |
1577 | |
6554 | 1578 @item sparse |
1579 Functions for handling sparse matrices. | |
1580 | |
3294 | 1581 @item specfun |
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1582 Special functions such as @code{bessel} or @code{factor}. |
3294 | 1583 |
1584 @item special-matrix | |
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1585 Functions that create special matrix forms such as Hilbert or Vandermonde |
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1586 matrices. |
3294 | 1587 |
1588 @item startup | |
1589 Octave's system-wide startup file. | |
1590 | |
1591 @item statistics | |
1592 Statistical functions. | |
1593 | |
1594 @item strings | |
1595 Miscellaneous string-handling functions. | |
1596 | |
6554 | 1597 @item testfun |
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1598 Functions for performing unit tests on other functions. |
6554 | 1599 |
3294 | 1600 @item time |
12632
2dbac27e0e40
doc: miscellaneous touch-ups to documentation strings
Rik <octave@nomad.inbox5.com>
parents:
12629
diff
changeset
|
1601 Functions related to time and date processing. |
3294 | 1602 @end table |