@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, or use a string as the name of a
function to call.  The @code{eval} and @code{feval} functions allow you
to do just that, and are necessary in order to evaluate commands that
are not known until run time, or to write functions that will need to
call user-supplied functions.

@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 string @var{catch}.
The string @var{try} is evaluated in the current context,
so any results remain available after @code{eval} returns.
@end deftypefn


@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


Here 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.  See @xref{Predicates for Numeric Objects}, for example,
for a list of predicates for numeric objects, and @xref{Status of
Variables}, for a description of the @code{exist} function.
