@c DO NOT EDIT!  Generated automatically by munge-texi.

@c Copyright (C) 1996, 1997 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.

@node Evaluation
@chapter Evaluation

Normally, you evaluate expressions simply by typing them at the Octave
prompt, or by asking Octave to interpret commands that you have saved in
a file.

Sometimes, you may find it necessary to evaluate an expression that has
been computed and stored in a string, which is exactly what the
@code{eval} lets you do.

@anchor{doc-eval}
@deftypefn {Built-in Function} {} eval (@var{try}, @var{catch})
Parse the string @var{try} and evaluate it as if it were an Octave
program.  If that fails, evaluate the optional string @var{catch}.
The string @var{try} is evaluated in the current context,
so any results remain available after @code{eval} returns.

The following example makes the variable @var{a} with the approximate
value 3.1416 available.

@example
eval("a = acos(-1);");
@end example

If an error occurs during the evaluation of @var{try} the @var{catch}
string is evaluated, as the following example shows.

@example
eval ('error ("This is a bad example");',
      'printf ("This error occured:\n%s", lasterr ());');
     @print{} This error occured:
        error: This is a bad example
@end example
@end deftypefn


@menu
* Calling a Function by its Name::
* Evaluation in a Different Context::
@end menu

@node Calling a Function by its Name
@section Calling a Function by its Name

The @code{feval} function allow you to call a function from a string
containing its name. This is useful when writing a function that need to
call user-supplied functions. The @code{feval} function takes the name
of the function to call as its first argument, and the remaining 
arguments are given to the function.

The following example is a simple-minded function using @code{feval}
that finds the root of a user-supplied function of one variable using
Newton's method.

@example
@group
@cindex Fordyce, A. P.
@findex newtroot
function result = newtroot (fname, x)

# usage: newtroot (fname, x)
#
#   fname : a string naming a function f(x).
#   x     : initial guess

  delta = tol = sqrt (eps);
  maxit = 200;
  fx = feval (fname, x);
  for i = 1:maxit
    if (abs (fx) < tol)
      result = x;
      return;
    else
      fx_new = feval (fname, x + delta);
      deriv = (fx_new - fx) / delta;
      x = x - fx / deriv;
      fx = fx_new;
    endif
  endfor

  result = x;

endfunction
@end group
@end example

Note that this is only meant to be an example of calling user-supplied
functions and should not be taken too seriously.  In addition to using a
more robust algorithm, any serious code would check the number and type
of all the arguments, ensure that the supplied function really was a
function, etc.  @xref{Predicates for Numeric Objects}, for example,
for a list of predicates for numeric objects, and see @ref{Status of
Variables}, for a description of the @code{exist} function.

@anchor{doc-feval}
@deftypefn {Built-in Function} {} feval (@var{name}, @dots{})
Evaluate the function named @var{name}.  Any arguments after the first
are passed on to the named function.  For example,

@example
feval ("acos", -1)
     @result{} 3.1416
@end example

@noindent
calls the function @code{acos} with the argument @samp{-1}.

The function @code{feval} is necessary in order to be able to write
functions that call user-supplied functions, because Octave does not
have a way to declare a pointer to a function (like C) or to declare a
special kind of variable that can be used to hold the name of a function
(like @code{EXTERNAL} in Fortran).  Instead, you must refer to functions
by name, and use @code{feval} to call them.
@end deftypefn


@node Evaluation in a Different Context
@section Evaluation in a Different Context

Before you evaluate an expression you need to substitute
the values of the variables used in the expression.  These
are stored in the symbol table.  Whenever the interpreter
starts a new function it saves the current symbol table
and creates a new one, initializing it with the list of
function parameters and a couple of predefined variables
such as @code{nargin}.  Expressions inside the function use the
new symbol table.

Sometimes you want to write a function so that when you
call it, it modifies variables in your own context.  This
allows you to use a pass-by-name style of function,
which is similar to using a pointer in programming languages such
as C.

Consider how you might write @code{save} and @code{load} as
m-files.  For example,

@example
function create_data
  x = linspace (0, 10, 10);
  y = sin (x);
  save mydata x y
endfunction
@end example

With @code{evalin}, you could write save as follows:

@example
function save (file, name1, name2)
  f = open_save_file (file);
  save_var(f, name1, evalin ("caller", name1));
  save_var(f, name2, evalin ("caller", name2));
endfunction
@end example

@noindent
Here, @samp{caller} is the @code{create_data} function and @code{name1}
is the string @code{"x"}, which evaluates simply as the value of @code{x}.

You later want to load the values back from @code{mydata}
in a different context:

@example
function process_data
  load mydata
  @dots{} do work @dots{}
endfunction
@end example

@noindent
With @code{assignin}, you could write @code{load} as follows:

@example
function load (file)
  f = open_load_file (file);
  [name, val] = load_var (f);
  assignin ("caller", name, val);
  [name, val] = load_var (f);
  assignin ("caller", name, val);
endfunction
@end example

@noindent
Here, @samp{caller} is the @code{process_data} function.

You can set and use variables at the command prompt
using the context @samp{base} rather than @samp{caller}.

These functions are rarely used in practice.  One
example is the @code{fail (@samp{code}, @samp{pattern})} function
which evaluates @samp{code} in the caller's context and
checks that the error message it produces matches
the given pattern.  Other examples such as @code{save} and @code{load}
are written in C++ where all octave variables
are in the @samp{caller} context and @code{evalin} is not needed.

@anchor{doc-evalin}
@deftypefn {Built-in Function} {} evalin (@var{context}, @var{try}, @var{catch})
Like @code{eval}, except that the expressions are evaluated in the
context @var{context}, which may be either @code{"caller"} or
@code{"base"}.
@end deftypefn


@anchor{doc-assignin}
@deftypefn {Built-in Function} {} assignin (@var{context}, @var{varname}, @var{value})
Assign @var{value} to @var{varname} in context @var{context}, which
may be either @code{"base"} or @code{"caller"}.
@end deftypefn

