diff doc/interpreter/func.txi @ 6570:49f0820425a8

[project @ 2007-04-24 23:06:56 by jwe]
author jwe
date Tue, 24 Apr 2007 23:07:44 +0000
parents e0e1c6df5ab2
children c9c504d939c5
line wrap: on
line diff
--- a/doc/interpreter/func.txi	Tue Apr 24 23:03:43 2007 +0000
+++ b/doc/interpreter/func.txi	Tue Apr 24 23:07:44 2007 +0000
@@ -23,7 +23,6 @@
 * Default Arguments::   
 * Function Files::              
 * Script Files::                
-* Dynamically Linked Functions::  
 * Function Handles and Inline::
 * Commands::
 * Organization of Functions::   
@@ -769,205 +768,6 @@
 
 @DOCSTRING(source)
 
-@node Dynamically Linked Functions
-@section Dynamically Linked Functions
-@cindex dynamic linking
-
-On some systems, Octave can dynamically load and execute functions
-written in C++.  Octave can only directly call functions written in C++,
-but you can also load functions written in other languages
-by calling them from a simple wrapper function written in C++.
-
-Here is an example of how to write a C++ function that Octave can load,
-with commentary.  The source for this function is included in the source
-distributions of Octave, in the file @file{examples/oregonator.cc}.  It
-defines the same set of differential equations that are used in the
-example problem of @ref{Ordinary Differential Equations}.  By running
-that example and this one, we can compare the execution times to see
-what sort of increase in speed you can expect by using dynamically
-linked functions.
-
-The function defined in @file{oregonator.cc} contains just 8 statements,
-and is not much different than the code defined in the corresponding
-M-file (also distributed with Octave in the file
-@file{examples/oregonator.m}).
-
-Here is the complete text of @file{oregonator.cc}:
-
-@example
-@group
-#include <octave/oct.h>
-
-DEFUN_DLD (oregonator, args, ,
-  "The `oregonator'.")
-@{
-  ColumnVector dx (3);
-
-  ColumnVector x (args(0).vector_value ());
-
-  dx(0) = 77.27 * (x(1) - x(0)*x(1) + x(0)
-                   - 8.375e-06*pow (x(0), 2));
-
-  dx(1) = (x(2) - x(0)*x(1) - x(1)) / 77.27;
-
-  dx(2) = 0.161*(x(0) - x(2));
-
-  return octave_value (dx);
-@}
-@end group
-@end example
-
-The first line of the file,
-
-@example
-#include <octave/oct.h>
-@end example
-
-@noindent
-includes declarations for all of Octave's internal functions that you
-will need.  If you need other functions from the standard C++ or C
-libraries, you can include the necessary headers here.
-
-The next two lines
-@example
-@group
-DEFUN_DLD (oregonator, args, ,
-  "The `oregonator'.")
-@end group
-@end example
-
-@noindent
-declares the function.  The macro @code{DEFUN_DLD} and the macros that
-it depends on are defined in the files @file{defun-dld.h},
-@file{defun.h}, and @file{defun-int.h} (these files are included in the
-header file @file{octave/oct.h}).
-
-Note that the third parameter to @code{DEFUN_DLD} (@code{nargout}) is
-not used, so it is omitted from the list of arguments in order to
-avoid the warning from gcc about an unused function parameter.
-
-The next line,
-
-@example
-ColumnVector dx (3);
-@end example
-
-@noindent
-simply declares an object to store the right hand sides of the
-differential equation, and the statement
-
-@example
-ColumnVector x (args(0).vector_value ());
-@end example
-
-@noindent
-extracts a vector from the first input argument.  The
-@code{vector_value} method is used so that the user of the function
-can pass either a row or column vector.  The @code{ColumnVector}
-constructor is needed because the ODE class requires a column
-vector.  The variable @code{args} is passed to functions defined with
-@code{DEFUN_DLD} as an @code{octave_value_list} object, which includes
-methods for getting the length of the list and extracting individual
-elements.
-
-In this example, we don't check for errors, but that is not difficult.
-All of the Octave's built-in functions do some form of checking on their
-arguments, so you can check the source code for those functions for
-examples of various strategies for verifying that the correct number and
-types of arguments have been supplied.
-
-The next statements
-
-@example
-@group
-dx(0) = 77.27 * (x(1) - x(0)*x(1) + x(0)
-                 - 8.375e-06*pow (x(0), 2));
-
-dx(1) = (x(2) - x(0)*x(1) - x(1)) / 77.27;
-
-dx(2) = 0.161*(x(0) - x(2));
-@end group
-@end example
-
-@noindent
-define the right-hand side of the differential equation.  Finally, we
-can return @code{dx}:
-
-@example
-return octave_value (dx);
-@end example
-
-@noindent
-The actual return type is @code{octave_value_list}, but it is only
-necessary to convert the return type to an @code{octave_value} because
-there is a default constructor that can automatically create an object
-of that type from an @code{octave_value} object, so we can just use that
-instead.
-
-To use this file, your version of Octave must support dynamic linking.
-To find out if it does, type the command
-@kbd{octave_config_info ("dld")} at the Octave prompt.  Support for
-dynamic linking is included if this command returns 1.
-
-To compile the example file, type the command @samp{mkoctfile
-oregonator.cc} at the shell prompt.  The script @code{mkoctfile} should
-have been installed along with Octave.  Running it will create a file
-called @file{oregonator.oct} that can be loaded by Octave.  To test the
-@file{oregonator.oct} file, start Octave and type the command
-
-@example
-oregonator ([1, 2, 3], 0)
-@end example
-
-@noindent
-at the Octave prompt.  Octave should respond by printing
-
-@example
-@group
-ans =
-
-   77.269353
-   -0.012942
-   -0.322000
-@end group
-@end example
-
-You can now use the @file{oregonator.oct} file just as you would the
-@code{oregonator.m} file to solve the set of differential equations.
-
-On a 133 MHz Pentium running Linux, Octave can solve the problem shown
-in @ref{Ordinary Differential Equations}, in about 1.4 seconds using the
-dynamically linked function, compared to about 19 seconds using the
-M-file.  Similar decreases in execution time can be expected for other
-functions, particularly those that rely on functions like @code{lsode}
-that require user-supplied functions.
-
-Just as for M-files, Octave will automatically reload a dynamically linked
-function when the file that defines it is more recent than the last
-time that the function was loaded.  If more than one function is defined
-in a single @file{.oct} file, reloading the file may force other
-functions to be cleared and reloaded.  If all the functions loaded from
-a given @file{.oct} file are cleared, Octave will automatically unload
-the @file{.oct} file.
-
-@c FIXME -- is there a better place for this?
-
-@DOCSTRING(variables_can_hide_functions)
-
-Additional examples for writing dynamically linked functions are
-available in the files in the @file{src} directory of the Octave
-distribution.
-
-There is currently no detailed description of all the functions that you
-can call in a built-in function.  For the time being, you will have to
-read the source code for Octave.
-
-@DOCSTRING(mkoctfile)
-
-@DOCSTRING(mex)
-
-@DOCSTRING(mexext)
-
 @node Function Handles and Inline
 @section Function Handles and Inline
 @cindex handle, function handles
@@ -1000,7 +800,7 @@
 @end example
 
 @noindent
-Creates a function handle called @code{f} that refers to the the
+Creates a function handle called @code{f} that refers to the
 function @code{sin}.
 
 Function handles are used to call other functions indirectly, or to pass
@@ -1010,20 +810,20 @@
 @example
 f = @@sin;
 quad (f, 0, pi)
-    @result 1.8391
+    @result{} 1.8391
 @end example
 
 You may use @code{feval} to call a function using function handle, or
-simply write the name of the function handle follwed by an argument
+simply write the name of the function handle followed by an argument
 list.  If there are no arguments, you must use an empty argument list
 @samp{()}.  For example
 
 @example
 f = @@sin;
 feval (f, pi/4)
-    @result 0.70711
+    @result{} 0.70711
 f (pi/4)
-    @result 0.70711
+    @result{} 0.70711
 @end example
 
 @DOCSTRING(functions)
@@ -1032,7 +832,7 @@
 
 @DOCSTRING(str2func)
 
-@node Anonymous Functions::
+@node Anonymous Functions
 @subsection Anonymous Functions
 
 Anonymous functions are defined using the syntax
@@ -1051,7 +851,7 @@
 @example
 f = @@(x) x.^2;
 quad (f, 0, 10)
-    @result 333.33
+    @result{} 333.33
 @end example
 
 @noindent
@@ -1060,7 +860,7 @@
 
 @example
 quad (@@(x) sin (x), 0, pi)
-    @result 1.8391
+    @result{} 1.8391
 @end example
 
 @noindent
@@ -1070,7 +870,7 @@
 a = 1;
 b = 2;
 quad (@@(x) betainc (x, a, b), 0, 0.4)
-    @result 1.3867
+    @result{} 1.3867
 @end example
 
 @noindent