Mercurial > octave
annotate doc/interpreter/eval.txi @ 12578:f5a780d675a1
Clean up operator and function indices in documentation.
| author | Rik <octave@nomad.inbox5.com> |
|---|---|
| date | Wed, 06 Apr 2011 11:44:21 -0700 |
| parents | fd0a3ac60b0e |
| children | 72c96de7a403 |
| rev | line source |
|---|---|
| 11523 | 1 @c Copyright (C) 1996-2011 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. | |
| 9 @c | |
| 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. | |
| 14 @c | |
| 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 Evaluation |
| 3294 | 20 @chapter Evaluation |
| 21 | |
| 22 Normally, you evaluate expressions simply by typing them at the Octave | |
| 23 prompt, or by asking Octave to interpret commands that you have saved in | |
| 24 a file. | |
| 25 | |
| 26 Sometimes, you may find it necessary to evaluate an expression that has | |
| 6641 | 27 been computed and stored in a string, which is exactly what the |
|
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
7018
diff
changeset
|
28 @code{eval} function lets you do. |
| 3294 | 29 |
| 3371 | 30 @DOCSTRING(eval) |
| 3294 | 31 |
| 6641 | 32 @menu |
| 33 * Calling a Function by its Name:: | |
| 34 * Evaluation in a Different Context:: | |
| 35 @end menu | |
| 36 | |
| 37 @node Calling a Function by its Name | |
| 38 @section Calling a Function by its Name | |
| 3294 | 39 |
| 7001 | 40 The @code{feval} function allows you to call a function from a string |
|
9037
4cb9f994dcec
Documentation cleanup of var.texi, expr.texi, eval.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
41 containing its name. This is useful when writing a function that needs to |
|
4cb9f994dcec
Documentation cleanup of var.texi, expr.texi, eval.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
42 call user-supplied functions. The @code{feval} function takes the name |
| 6641 | 43 of the function to call as its first argument, and the remaining |
| 44 arguments are given to the function. | |
| 45 | |
| 46 The following example is a simple-minded function using @code{feval} | |
| 47 that finds the root of a user-supplied function of one variable using | |
| 48 Newton's method. | |
| 3294 | 49 |
| 50 @example | |
| 51 function result = newtroot (fname, x) | |
| 52 | |
| 53 # usage: newtroot (fname, x) | |
| 54 # | |
| 55 # fname : a string naming a function f(x). | |
| 56 # x : initial guess | |
| 57 | |
| 58 delta = tol = sqrt (eps); | |
| 59 maxit = 200; | |
| 60 fx = feval (fname, x); | |
| 61 for i = 1:maxit | |
| 62 if (abs (fx) < tol) | |
| 63 result = x; | |
| 64 return; | |
| 65 else | |
| 66 fx_new = feval (fname, x + delta); | |
| 67 deriv = (fx_new - fx) / delta; | |
| 68 x = x - fx / deriv; | |
| 69 fx = fx_new; | |
| 70 endif | |
| 71 endfor | |
| 72 | |
| 73 result = x; | |
| 74 | |
| 75 endfunction | |
| 76 @end example | |
| 77 | |
| 78 Note that this is only meant to be an example of calling user-supplied | |
| 79 functions and should not be taken too seriously. In addition to using a | |
| 80 more robust algorithm, any serious code would check the number and type | |
| 81 of all the arguments, ensure that the supplied function really was a | |
| 6641 | 82 function, etc. @xref{Predicates for Numeric Objects}, for example, |
| 83 for a list of predicates for numeric objects, and see @ref{Status of | |
| 3294 | 84 Variables}, for a description of the @code{exist} function. |
| 6549 | 85 |
| 6641 | 86 @DOCSTRING(feval) |
| 87 | |
| 6863 | 88 A similar function @code{run} exists for calling user script files, that |
| 89 are not necessarily on the user path | |
| 90 | |
| 91 @DOCSTRING(run) | |
| 92 | |
| 6641 | 93 @node Evaluation in a Different Context |
| 94 @section Evaluation in a Different Context | |
| 95 | |
| 96 Before you evaluate an expression you need to substitute | |
| 97 the values of the variables used in the expression. These | |
| 98 are stored in the symbol table. Whenever the interpreter | |
| 99 starts a new function it saves the current symbol table | |
| 100 and creates a new one, initializing it with the list of | |
| 101 function parameters and a couple of predefined variables | |
| 102 such as @code{nargin}. Expressions inside the function use the | |
| 103 new symbol table. | |
| 104 | |
| 105 Sometimes you want to write a function so that when you | |
| 106 call it, it modifies variables in your own context. This | |
| 107 allows you to use a pass-by-name style of function, | |
| 108 which is similar to using a pointer in programming languages such | |
| 109 as C. | |
| 110 | |
| 111 Consider how you might write @code{save} and @code{load} as | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
9209
diff
changeset
|
112 m-files. For example: |
| 6641 | 113 |
| 114 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9037
diff
changeset
|
115 @group |
| 6641 | 116 function create_data |
| 117 x = linspace (0, 10, 10); | |
| 118 y = sin (x); | |
| 119 save mydata x y | |
| 120 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9037
diff
changeset
|
121 @end group |
| 6641 | 122 @end example |
| 123 | |
| 8828 | 124 With @code{evalin}, you could write @code{save} as follows: |
| 6641 | 125 |
| 126 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9037
diff
changeset
|
127 @group |
| 6641 | 128 function save (file, name1, name2) |
| 129 f = open_save_file (file); | |
| 130 save_var(f, name1, evalin ("caller", name1)); | |
| 131 save_var(f, name2, evalin ("caller", name2)); | |
| 132 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9037
diff
changeset
|
133 @end group |
| 6641 | 134 @end example |
| 135 | |
| 136 @noindent | |
| 137 Here, @samp{caller} is the @code{create_data} function and @code{name1} | |
| 138 is the string @code{"x"}, which evaluates simply as the value of @code{x}. | |
| 139 | |
| 140 You later want to load the values back from @code{mydata} | |
| 141 in a different context: | |
| 142 | |
| 143 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9037
diff
changeset
|
144 @group |
| 6641 | 145 function process_data |
| 146 load mydata | |
| 147 @dots{} do work @dots{} | |
| 148 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9037
diff
changeset
|
149 @end group |
| 6641 | 150 @end example |
| 151 | |
| 152 @noindent | |
| 153 With @code{assignin}, you could write @code{load} as follows: | |
| 154 | |
| 155 @example | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9037
diff
changeset
|
156 @group |
| 6641 | 157 function load (file) |
| 158 f = open_load_file (file); | |
| 159 [name, val] = load_var (f); | |
| 160 assignin ("caller", name, val); | |
| 161 [name, val] = load_var (f); | |
| 162 assignin ("caller", name, val); | |
| 163 endfunction | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9037
diff
changeset
|
164 @end group |
| 6641 | 165 @end example |
| 166 | |
| 167 @noindent | |
| 168 Here, @samp{caller} is the @code{process_data} function. | |
| 169 | |
| 170 You can set and use variables at the command prompt | |
| 171 using the context @samp{base} rather than @samp{caller}. | |
| 172 | |
| 173 These functions are rarely used in practice. One | |
| 174 example is the @code{fail (@samp{code}, @samp{pattern})} function | |
| 175 which evaluates @samp{code} in the caller's context and | |
| 176 checks that the error message it produces matches | |
| 177 the given pattern. Other examples such as @code{save} and @code{load} | |
|
8481
00df69d7e698
[docs] capitalize Octave consistently
Brian Gough <bjg@gnu.org>
parents:
8347
diff
changeset
|
178 are written in C++ where all Octave variables |
| 6641 | 179 are in the @samp{caller} context and @code{evalin} is not needed. |
| 180 | |
| 6549 | 181 @DOCSTRING(evalin) |
| 182 | |
| 183 @DOCSTRING(assignin) |