Mercurial > hg > octave-shane
changeset 16867:be41c30bcb44
Re-write documentation and all examples of dynamically linked functions.
* doc/interpreter/dynamic.txi: deleted.
* doc/interpreter/external.txi: Renamed from dynamic.txi. Rewrote or added
much information about dynamically linked functions.
* doc/interpreter/Makefile.am: Changed dynamic.txi to external.txi
in build system.
* doc/interpreter/data.txi, doc/interpreter/intro.txi,
doc/interpreter/octave.texi, doc/interpreter/sparse.txi: Changed dynamic.txi to
external.txi in cross-references.
* doc/interpreter/doccheck/aspell-octave.en.pws: Added new words from
external.txi to Octave dictionary.
* examples/firstmexdemo.c: deleted.
* examples/mex_demo.c: Renamed from firstmexdemo.c. Added many more comments
to code.
* examples/hello.cc: deleted.
* examples/oct_demo.cc: Renamed from hello.cc. Added many more comments
to code.
* examples/Makefile.am: Changed build system to use mex_demo.c and oct_demo.cc.
* examples/addtwomatrices.cc, examples/celldemo.cc, examples/embedded.cc,
examples/fortdemo.cc, examples/funcdemo.cc, examples/globaldemo.cc,
examples/helloworld.cc, examples/mycell.c, examples/myfeval.c,
examples/myfunc.c, examples/myhello.c, examples/mypow2.c, examples/myprop.c,
examples/myset.c, examples/mysparse.c, examples/mystring.c,
examples/mystruct.c, examples/paramdemo.cc, examples/standalone.cc,
examples/stringdemo.cc, examples/structdemo.cc, examples/unwinddemo.cc:
Use Octave coding conventions for code. Fixed all compilation errors and
warnings.
| author | Rik <rik@octave.org> |
|---|---|
| date | Sat, 29 Jun 2013 18:08:24 -0700 |
| parents | a472bfc67b6c |
| children | b028df1b1e81 |
| files | doc/interpreter/Makefile.am doc/interpreter/data.txi doc/interpreter/doccheck/aspell-octave.en.pws doc/interpreter/dynamic.txi doc/interpreter/external.txi doc/interpreter/intro.txi doc/interpreter/octave.texi doc/interpreter/sparse.txi examples/Makefile.am examples/addtwomatrices.cc examples/celldemo.cc examples/embedded.cc examples/firstmexdemo.c examples/fortdemo.cc examples/funcdemo.cc examples/globaldemo.cc examples/hello.cc examples/helloworld.cc examples/mex_demo.c examples/mycell.c examples/myfeval.c examples/myfunc.c examples/myhello.c examples/mypow2.c examples/myprop.c examples/myset.c examples/mysparse.c examples/mystring.c examples/mystruct.c examples/oct_demo.cc examples/paramdemo.cc examples/standalone.cc examples/stringdemo.cc examples/structdemo.cc examples/unwinddemo.cc |
| diffstat | 32 files changed, 644 insertions(+), 555 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/interpreter/Makefile.am +++ b/doc/interpreter/Makefile.am @@ -58,7 +58,6 @@ $(top_srcdir)/examples/addtwomatrices.cc \ $(top_srcdir)/examples/celldemo.cc \ $(top_srcdir)/examples/embedded.cc \ - $(top_srcdir)/examples/firstmexdemo.c \ $(top_srcdir)/examples/fortdemo.cc \ $(top_srcdir)/examples/fortsub.f \ $(top_srcdir)/examples/funcdemo.cc \ @@ -67,6 +66,7 @@ $(top_srcdir)/examples/mycell.c \ $(top_srcdir)/examples/myfeval.c \ $(top_srcdir)/examples/myfunc.c \ + $(top_srcdir)/examples/myhello.c \ $(top_srcdir)/examples/mypow2.c \ $(top_srcdir)/examples/mysparse.c \ $(top_srcdir)/examples/mystring.c \ @@ -125,7 +125,7 @@ debug.texi \ diffeq.texi \ diagperm.texi \ - dynamic.texi \ + external.texi \ emacs.texi \ errors.texi \ eval.texi \
--- a/doc/interpreter/data.txi +++ b/doc/interpreter/data.txi @@ -27,10 +27,10 @@ It is also possible to define new specialized data types by writing a small amount of C++ code. On some systems, new data types can be loaded dynamically while Octave is running, so it is not necessary to recompile -all of Octave just to add a new type. @xref{Dynamically Linked -Functions}, for more information about Octave's dynamic linking -capabilities. @ref{User-defined Data Types} describes what you must do -to define a new data type for Octave. +all of Octave just to add a new type. @xref{External Code Interface}, for +more information about Octave's dynamic linking capabilities. +@ref{User-defined Data Types} describes what you must do to define a +new data type for Octave. @DOCSTRING(typeinfo)
--- a/doc/interpreter/doccheck/aspell-octave.en.pws +++ b/doc/interpreter/doccheck/aspell-octave.en.pws @@ -20,9 +20,11 @@ anova Anymap API +APIs appdata approximant arg +args ARMA arpack ascii @@ -140,6 +142,7 @@ cmd cmember cntrl +codebases cof coffset colamd
rename from doc/interpreter/dynamic.txi rename to doc/interpreter/external.txi --- a/doc/interpreter/dynamic.txi +++ b/doc/interpreter/external.txi @@ -17,50 +17,91 @@ @c along with Octave; see the file COPYING. If not, see @c <http://www.gnu.org/licenses/>. -@node Dynamically Linked Functions -@appendix Dynamically Linked Functions +@node External Code Interface +@appendix External Code Interface @cindex dynamic-linking +@cindex Dynamically Linked Functions +@cindex Octave API + +“The sum of human wisdom is not contained in any one language" + ---Ezra Pound -Octave has the possibility of including compiled code as dynamically -linked extensions and then using these extensions as if they were part -of Octave itself. Octave can call C++ code -through its native oct-file interface or C code through its mex -interface. It can also indirectly call functions written in any other -language through a simple wrapper. The reasons to write code in a -compiled language might be either to link to an existing piece of code -and allow it to be used within Octave, or to allow improved performance -for key pieces of code. +Octave is a fantastic language for solving many problems in science and +engineering. However, it is not the only computer language and there +are times when you may want to use code written in other languages. +Good reasons for doing so include: 1) not re-inventing the wheel; existing +function libraries which have been thoroughly tested and debugged or +large scale simulation codebases are a good example, 2) accessing unique +capabilities of a different language; for example the well-known regular +expression functions of Perl (but don't do that because @code{regexp} +already exists in Octave). -Before going further, you should first determine if you really need to -use dynamically linked functions at all. Before proceeding with writing -any dynamically linked function to improve performance you should -address ask yourself +Performance should generally @strong{not} be a reason for using compiled +extensions. Although compiled extensions can run faster, particularly +if they replace a loop in Octave code, this is almost never the best path +to take. First, there are many techniques to speed up Octave performance while +remaining within the language. Second, Octave is a high-level language that +makes it easy to perform common mathematical tasks. Giving that up means +shifting the focus from solving the real problem to solving a computer +programming problem. It means returning to low-level constructs such as +pointers, memory management, mathematical overflow/underflow, etc. Because +of the low level nature, and the fact that the compiled code is executed outside +of Octave, there is the very real possibility of crashing the interpreter and +losing work. + +Before going further, you should first determine if you really need to bother +writing code outside of Octave. @itemize @bullet @item -Can I get the same functionality using the Octave scripting language only? +Can I get the same functionality using the Octave scripting language alone? + +Even when a function already exists outside the language, it may be +better to simply reproduce the behavior in an m-file rather than attempt to +interface to the outside code. @item -Is it thoroughly optimized Octave code? Vectorization of Octave code, -doesn't just make it concise, it generally significantly improves its -performance. Above all, if loops must be used, make sure that the -allocation of space for variables takes place outside the loops using an -assignment to a matrix of the right size, or zeros. +Is the code thoroughly optimized for Octave? + +If performance is an issue you should always start with the in-language +techniques for getting better performance. Chief among these is vectorization +(@pxref{Vectorization and Faster Code Execution}) which not only makes the +code concise and more understandable but improves performance (10X-100X). +If loops must be used, make sure that the allocation of space for variables +takes place outside the loops using an assignment to a matrix of the right +size, or zeros. @item -Does it make as much use as possible of existing built-in library -routines? These are highly optimized and many do not carry the overhead +Does the code make as much use as possible of existing built-in library +routines? + +These routines are highly optimized and many do not carry the overhead of being interpreted. @item -Does writing a dynamically linked function represent useful investment +Does writing a dynamically linked function represent a useful investment of your time, relative to staying in Octave? + +It will take time to learn Octave's interface for external code and +there will inevitably be issues with tools such as compilers. @end itemize -Also, as oct- and mex-files are dynamically linked to Octave, they -introduce the possibility of Octave crashing due to errors in -the user code. For example a segmentation violation in the user's code -will cause Octave to abort. +With that said, Octave offers a versatile interface for including chunks +of compiled code as dynamically linked extensions. These dynamically linked +functions can be called from the interpreter in the same manner as any +ordinary function. The interface is bi-directional and external code can +call Octave functions (like @code{plot}) which otherwise might be very +difficult to develop. + +The interface is centered around supporting the languages C++, C, and Fortran. +Octave itself is written in C++ and can call external C++/C code through its +native oct-file interface. The C language is also supported through the +mex-file interface for compatibility with @sc{matlab}. Fortran code is easiest +to reach through the oct-file interface. + +Because many other languages provide C or C++ APIs it is relatively simple +to build bridges between Octave and other languages. This is also a way to +bridge to hardware resources which often have device drivers written in C. @menu * Oct-Files:: @@ -94,12 +135,19 @@ @node Getting Started with Oct-Files @subsection Getting Started with Oct-Files -The basic command to build oct-files is @code{mkoctfile} and it can be -call from within octave or from the command line. +Oct-files are pieces of C++ code that have been compiled with the Octave +API into a dynamically loadable object. They take their name from the file +which contains the object which has the extension @file{.oct}. + +Finding a C++ compiler, using the correct switches, adding the right include +paths for header files, etc. is a difficult task. Octave automates this by +providing the @code{mkoctfile} command with which to build oct-files. The +command is available from within Octave or at the shell command line. @DOCSTRING(mkoctfile) -Consider the short C++ example: +Consider the following short example which introduces the basics of +writing a C++ function that can be linked to Octave. @example @group @@ -107,17 +155,14 @@ @end group @end example -This example although short introduces the basics of writing a C++ -function that can be dynamically linked to Octave. The easiest way to -make available most of the definitions that might be necessary for a C++ -oct-file in Octave is to use the @code{#include <octave/oct.h>} header. +The first critical line is @code{#include <octave/oct.h>} which +makes available most of the definitions necessary for a C++ oct-file. Note that @file{octave/oct.h} is a C++ header and cannot be directly -@code{#include}'ed in a C source file, nor any other language. What -follows is mostly C++, with a discussion of other languages in section -@ref{Calling External Code from Oct-Files}. +@code{#include}'ed in a C source file, nor any other language. -The macro that defines the entry point into the dynamically loaded -function is @w{@code{DEFUN_DLD}}. This macro takes four arguments, these being +Included by @file{oct.h} is a definition for the macro +@w{@code{DEFUN_DLD}} which creates a dynamically loaded function. This +macro takes four arguments: @enumerate 1 @item The function name as it will be seen in Octave, @@ -127,36 +172,35 @@ @item The number of output arguments, which can and often is omitted if not used, and -@item The string that will be seen as the help text of the function. +@item The string to use for the help text of the function. @end enumerate The return type of functions defined with @w{@code{DEFUN_DLD}} is always @code{octave_value_list}. There are a couple of important considerations in the choice of function -name. Firstly, it must be a valid Octave function name and so must be a -sequence of letters, digits and underscores, not starting with a -digit. Secondly, as Octave uses the function name to define the filename +name. First, it must be a valid Octave function name and so must be a +sequence of letters, digits, and underscores not starting with a +digit. Second, as Octave uses the function name to define the filename it attempts to find the function in, the function name in the @w{@code{DEFUN_DLD}} macro must match the filename of the oct-file. Therefore, -the above function should be in a file @file{helloworld.cc}, and it should be +the above function should be in a file @file{helloworld.cc}, and would be compiled to an oct-file using the command @example mkoctfile helloworld.cc @end example -This will create a file called @file{helloworld.oct}, that is the compiled +This will create a file called @file{helloworld.oct} that is the compiled version of the function. It should be noted that it is perfectly acceptable to have more than one @w{@code{DEFUN_DLD}} function in a source file. However, there must either be a symbolic link to the oct-file for each of the functions defined in the source code with the @w{@code{DEFUN_DLD}} -macro or the autoload (@ref{Function Files}) function should be used. +macro or the @code{autoload} (@ref{Function Files}) function should be used. -The rest of this function then shows how to find the number of input -arguments, how to print through the octave pager, and return from the -function. After compiling this function as above, an example of its use -is +The rest of the function shows how to find the number of input arguments, +how to print through the Octave pager, and return from the function. After +compiling this function as above, an example of its use is @example @group @@ -165,6 +209,13 @@ @end group @end example +Subsequent sections show how to use specific classes from Octave's core +internals. Base classes like dMatrix (a matrix of double values) are +found in the directory @file{liboctave/array}. The definitive reference for +how to use a particular class is the header file itself. However, it is +often enough just to study the examples in the manual in order to be able +to use the class. + @node Matrices and Arrays in Oct-Files @subsection Matrices and Arrays in Oct-Files @@ -175,18 +226,17 @@ @table @code @item Matrix -A double precision matrix class defined in dMatrix.h, +A double precision matrix class defined in @file{dMatrix.h}, @item ComplexMatrix -A complex matrix class defined in CMatrix.h, and +A complex matrix class defined in @file{CMatrix.h}, and @item BoolMatrix -A boolean matrix class defined in boolMatrix.h. +A boolean matrix class defined in @file{boolMatrix.h}. @end table -These are the basic two-dimensional matrix types of octave. In -additional there are a number of multi-dimensional array types, these -being +These are the basic two-dimensional matrix types of Octave. In +addition there are a number of multi-dimensional array types including @table @code @item NDArray @@ -198,49 +248,48 @@ @item boolNDArray A boolean array class defined in @file{boolNDArray.h} -@item int8NDArray +@item int8NDArray @itemx int16NDArray @itemx int32NDArray @itemx int64NDArray -8, 16, 32 and 64-bit signed array classes defined in +8, 16, 32, and 64-bit signed array classes defined in @file{int8NDArray.h}, @file{int16NDArray.h}, etc. -@item uint8NDArray +@item uint8NDArray @itemx uint16NDArray @itemx uint32NDArray @itemx uint64NDArray -8, 16, 32 and 64-bit unsigned array classes defined in +8, 16, 32, and 64-bit unsigned array classes defined in @file{uint8NDArray.h}, @file{uint16NDArray.h}, etc. @end table -There are several basic means of constructing matrices of -multi-dimensional arrays. Considering the @code{Matrix} type as an -example +There are several basic ways of constructing matrices or +multi-dimensional arrays. Using the class @code{Matrix} as an example +one can @itemize @bullet @item -We can create an empty matrix or array with the empty constructor. For -example +Create an empty matrix or array with the empty constructor. For example: @example Matrix a; @end example -This can be used on all matrix and array types +This can be used for all matrix and array types. @item -Define the dimensions of the matrix or array with a dim_vector. For -example +Define the dimensions of the matrix or array with a dim_vector which has +the same characteristics as the vector returned from @code{size}. For example: @example @group dim_vector dv (2); -dv(0) = 2; dv(1) = 2; +dv(0) = 2; dv(1) = 3; // 2 rows, 3 columns Matrix a (dv); @end group @end example -This can be used on all matrix and array types +This can be used on all matrix and array types. @item Define the number of rows and columns in the matrix. For example: @@ -249,11 +298,12 @@ Matrix a (2, 2) @end example -However, this constructor can only be used with the matrix types. +However, this constructor can only be used with matrix types. @end itemize -These types all share a number of basic methods and operators, a -selection of which include +These types all share a number of basic methods and operators. Many bear +a resemblance to functions that exist in the interpreter. A selection of +useful methods include @deftypefn Method T& {operator ()} (octave_idx_type) @deftypefnx Method T& elem (octave_idx_type) @@ -269,7 +319,7 @@ circumstances the user might prefer to access the data of the array or matrix directly through the @nospell{fortran_vec} method discussed below. -@deftypefn Method octave_idx_type nelem (void) const +@deftypefn Method octave_idx_type numel (void) const The total number of elements in the matrix or array. @end deftypefn @@ -281,6 +331,11 @@ The dimensions of the matrix or array in value of type dim_vector. @end deftypefn +@deftypefn Method int ndims (void) const +The number of dimensions of the matrix or array. Matrices are 2-D, +but arrays can be N-dimensional. +@end deftypefn + @deftypefn Method void resize (const dim_vector&) A method taking either an argument of type @code{dim_vector}, or in the case of a matrix two arguments of type @code{octave_idx_type} defining @@ -288,14 +343,14 @@ @end deftypefn @deftypefn Method T* fortran_vec (void) -This method returns a pointer to the underlying data of the matrix or a +This method returns a pointer to the underlying data of the matrix or array so that it can be manipulated directly, either within Octave or by an external library. @end deftypefn Operators such an @code{+}, @code{-}, or @code{*} can be used on the -majority of the above types. In addition there are a number of methods -that are of interest only for matrices such as @code{transpose}, +majority of the matrix and array types. In addition there are a number of +methods that are of interest only for matrices such as @code{transpose}, @code{hermitian}, @code{solve}, etc. The typical way to extract a matrix or array from the input arguments of @@ -307,7 +362,7 @@ @end group @end example -To avoid segmentation faults causing Octave to abort, this function +To avoid segmentation faults causing Octave to abort this function explicitly checks that there are sufficient arguments available before accessing these arguments. It then obtains two multi-dimensional arrays of type @code{NDArray} and adds these together. Note that the array_value @@ -320,22 +375,22 @@ @code{A + B}, operating on two @code{NDArray}'s returns an @code{NDArray}, which is cast to an @code{octave_value} on the return -from the function. An example of the use of this demonstration function -is +from the function. An example of the use of this demonstration function is @example @group -addtwomatrices (ones (2, 2), ones (2, 2)) - @result{} 2 2 - 2 2 +addtwomatrices (ones (2, 2), eye (2, 2)) + @result{} 2 1 + 1 2 @end group @end example A list of the basic @code{Matrix} and @code{Array} types, the methods to -extract these from an @code{octave_value} and the associated header is +extract these from an @code{octave_value}, and the associated header file is listed below. @multitable @columnfractions .3 .4 .3 +@headitem Type @tab Function @tab Source Code @item @code{RowVector} @tab @code{row_vector_value} @tab @file{dRowVector.h} @item @code{ComplexRowVector} @tab @code{complex_row_vector_value} @tab @file{CRowVector.h} @item @code{ColumnVector} @tab @code{column_vector_value} @tab @file{dColVector.h} @@ -361,7 +416,7 @@ @node Character Strings in Oct-Files @subsection Character Strings in Oct-Files -In Octave a character string is just a special @code{Array} class. +A character string in Octave is just a special @code{Array} class. Consider the example: @example @@ -389,20 +444,19 @@ One additional complication of strings in Octave is the difference between single quoted and double quoted strings. To find out if an -@code{octave_value} contains a single or double quoted string an example is +@code{octave_value} contains a single or double quoted string use +one of the predicate tests shown below. @example @group - if (args(0).is_sq_string ()) - octave_stdout << - "First argument is a singularly quoted string\n"; - else if (args(0).is_dq_string ()) - octave_stdout << - "First argument is a doubly quoted string\n"; +if (args(0).is_sq_string ()) + octave_stdout << "First argument is a single quoted string\n"; +else if (args(0).is_dq_string ()) + octave_stdout << "First argument is a double quoted string\n"; @end group @end example -Note however, that both types of strings are represented by the +Note, however, that both types of strings are represented by the @code{charNDArray} type, and so when assigning to an @code{octave_value}, the type of string should be specified. For example: @@ -412,19 +466,21 @@ charNDArray c; @dots{} // Create single quoted string -retval(1) = octave_value (ch, true, '\''); +retval(1) = octave_value (ch); // default constructor is sq_string + OR +retval(1) = octave_value (ch, '\''); // explicitly create sq_string // Create a double quoted string -retval(0) = octave_value (ch, true); +retval(0) = octave_value (ch, '"'); @end group @end example @node Cell Arrays in Oct-Files @subsection Cell Arrays in Oct-Files -Octave's cell type is equally accessible within oct-files. A cell -array is just an array of @code{octave_value}s, and so each element of the cell -array can then be treated just like any other @code{octave_value}. A simple +Octave's cell type is also available from within oct-files. A cell +array is just an array of @code{octave_value}s, and thus each element of the +cell array can be treated just like any other @code{octave_value}. A simple example is @example @@ -434,9 +490,9 @@ @end example Note that cell arrays are used less often in standard oct-files and so -the @file{Cell.h} header file must be explicitly included. The rest of this +the @file{Cell.h} header file must be explicitly included. The rest of the example extracts the @code{octave_value}s one by one from the cell array and -returns be as individual return arguments. For example consider +returns them as individual return arguments. For example: @example @group @@ -454,9 +510,9 @@ @node Structures in Oct-Files @subsection Structures in Oct-Files -A structure in Octave is map between a number of fields represented and +A structure in Octave is a map between a number of fields represented and their values. The Standard Template Library @code{map} class is used, -with the pair consisting of a @code{std::string} and an octave +with the pair consisting of a @code{std::string} and an Octave @code{Cell} variable. A simple example demonstrating the use of structures within oct-files is @@ -475,28 +531,31 @@ @end group @end example -The commented code above demonstrates how to iterate over all of the -fields of the structure, where as the following code demonstrates finding -a particular field in a more concise manner. - -As can be seen the @code{contents} method of the @code{Octave_map} class -returns a @code{Cell} which allows structure arrays to be represented. -Therefore, to obtain the underlying @code{octave_value} we write +The example above specifically uses the @code{octave_scalar_map} class which +is for representing a single struct. For structure arrays the +@code{octave_map} class is used instead. The commented code shows how the +demo could be modified to handle a structure array. In that case the +@code{contents} method returns a @code{Cell} which may have more than one +element. Therefore, to obtain the underlying @code{octave_value} in +this single-struct example we write @example -octave_value tmp = arg0.contents (p1) (0); +octave_value tmp = arg0.contents (arg1)(0); @end example @noindent -where the trailing (0) is the () operator on the @code{Cell} object. We -can equally iterate of the elements of the Cell array to address the -elements of the structure array. +where the trailing (0) is the () operator on the @code{Cell} object. If +this were a true structure array with multiple elements we could iterate +over the elements using the () operator. + +Structures are a relatively complex data container and there are more +functions available in @file{oct-map.h} which make coding with them easier +than relying on just @code{contents}. @node Sparse Matrices in Oct-Files @subsection Sparse Matrices in Oct-Files -There are three classes of sparse objects that are of interest to the -user. +There are three classes of sparse objects that are of interest to the user. @table @code @item SparseMatrix @@ -511,19 +570,18 @@ All of these classes inherit from the @code{Sparse<T>} template class, and so all have similar capabilities and usage. The @code{Sparse<T>} -class was based on Octave @code{Array<T>} class, and so users familiar +class was based on Octave's @code{Array<T>} class, and so users familiar with Octave's @code{Array} classes will be comfortable with the use of the sparse classes. The sparse classes will not be entirely described in this section, due to their similarity with the existing @code{Array} classes. However, there are a few differences due the different nature of sparse objects, -and these will be described. Firstly, although it is fundamentally +and these will be described. First, although it is fundamentally possible to have N-dimensional sparse objects, the Octave sparse classes do -not allow them at this time. So all operations of the sparse classes -must be 2-dimensional. This means that in fact @code{SparseMatrix} is -similar to Octave's @code{Matrix} class rather than its -@code{NDArray} class. +not allow them at this time; All instances of the sparse classes +must be 2-dimensional. This means that @code{SparseMatrix} is actually +more similar to Octave's @code{Matrix} class than its @code{NDArray} class. @menu * Array and Sparse Differences:: @@ -571,8 +629,7 @@ @dots{} for (int j = 0; j < nc; j++) for (int i = 0; i < nr; i++) - std::cerr << " (" << i << "," << j << "): " << sm(i,j) - << std::endl; + std::cerr << " (" << i << "," << j << "): " << sm(i,j) << std::endl; @end group @end example @@ -594,32 +651,30 @@ const SparseMatrix tmp (sm); for (int j = 0; j < nc; j++) for (int i = 0; i < nr; i++) - std::cerr << " (" << i << "," << j << "): " << tmp(i,j) - << std::endl; + std::cerr << " (" << i << "," << j << "): " << tmp(i,j) << std::endl; @end group @end example -Finally, as the sparse types aren't just represented as a contiguous +Finally, as the sparse types aren't represented by a contiguous block of memory, the @nospell{@code{fortran_vec}} method of the @code{Array<T>} -is not available. It is however replaced by three separate methods +is not available. It is, however, replaced by three separate methods @code{ridx}, @code{cidx} and @code{data}, that access the raw compressed -column format that the Octave sparse matrices are stored in. -Additionally, these methods can be used in a manner similar to @code{elem}, -to allow the matrix to be accessed or filled. However, in that case it is -up to the user to respect the sparse matrix compressed column format -discussed previous. +column format that Octave sparse matrices are stored in. These methods can be +used in a manner similar to @code{elem} to allow the matrix to be accessed or +filled. However, in that case it is up to the user to respect the sparse +matrix compressed column format. @node Creating Sparse Matrices in Oct-Files @subsubsection Creating Sparse Matrices in Oct-Files -You have several alternatives for creating a sparse matrix. -You can first create the data as three vectors representing the -row and column indexes and the data, and from those create the matrix. -Or alternatively, you can create a sparse matrix with the appropriate +There are several useful alternatives for creating a sparse matrix. +The first is to create three vectors representing the row index, column index, +and data values, and from these create the matrix. +The second alternative is to create a sparse matrix with the appropriate amount of space and then fill in the values. Both techniques have their advantages and disadvantages. -Here is an example of how to create a small sparse matrix with the first +Below is an example of creating a small sparse matrix using the first technique @example @@ -630,10 +685,10 @@ ColumnVector cidx (nz); ColumnVector data (nz); -ridx(0) = 0; ridx(1) = 0; ridx(2) = 1; ridx(3) = 2; -cidx(0) = 0; cidx(1) = 1; cidx(2) = 3; cidx(3) = 3; -data(0) = 1; data(1) = 2; data(2) = 3; data(3) = 4; - +ridx(0) = 0; cidx(0) = 0; data(0) = 1; +ridx(1) = 0; cidx(1) = 1; data(1) = 2; +ridx(2) = 1; cidx(2) = 3; data(2) = 3; +ridx(3) = 2; cidx(3) = 3; data(3) = 4; SparseMatrix sm (data, ridx, cidx, nr, nc); @end group @end example @@ -642,21 +697,21 @@ which creates the matrix given in section @ref{Storage of Sparse Matrices}. Note that the compressed matrix format is not used at the time of the creation of the matrix itself, -however it is used internally. +but is used internally. -As previously mentioned, the values of the sparse matrix are stored -in increasing column-major ordering. Although the data passed by the -user does not need to respect this requirement, the pre-sorting the -data significantly speeds up the creation of the sparse matrix. +As discussed in the chapter on Sparse Matrices, the values of the sparse +matrix are stored in increasing column-major ordering. Although the data +passed by the user need not respect this requirement, pre-sorting the +data will significantly speed up creation of the sparse matrix. -The disadvantage of this technique of creating a sparse matrix is -that there is a brief time where two copies of the data exists. Therefore -for extremely memory constrained problems this might not be the right -technique to create the sparse matrix. +The disadvantage of this technique for creating a sparse matrix is +that there is a brief time when two copies of the data exist. For +extremely memory constrained problems this may not be the best +technique for creating a sparse matrix. -The alternative is to first create the sparse matrix with the desired -number of non-zero elements and then later fill those elements in. The -easiest way to do this is +The alternative is to first create a sparse matrix with the desired +number of non-zero elements and then later fill those elements in. +Sample code: @example @group @@ -666,17 +721,16 @@ @end group @end example -That creates the same matrix as previously. Again, although it is not +This creates the same matrix as previously. Again, although not strictly necessary, it is significantly faster if the sparse matrix is -created in this manner that the elements are added in column-major -ordering. The reason for this is that if the elements are inserted -at the end of the current list of known elements then no element -in the matrix needs to be moved to allow the new element to be -inserted. Only the column indexes need to be updated. +created and the elements are added in column-major ordering. The reason +for this is that when elements are inserted at the end of the current list +of known elements then no element in the matrix needs to be moved to allow +the new element to be inserted; Only the column indexes need to be updated. -There are a few further points to note about this technique of creating -a sparse matrix. Firstly, it is possible to create a sparse matrix -with fewer elements than are actually inserted in the matrix. Therefore +There are a few further points to note about this method of creating +a sparse matrix. First, it is possible to create a sparse matrix +with fewer elements than are actually inserted in the matrix. Therefore, @example @group @@ -687,57 +741,52 @@ @end example @noindent -is perfectly valid. However it is a very bad idea. The reason is that -as each new element is added to the sparse matrix the space allocated -to it is increased by reallocating the memory. This is an expensive -operation, that will significantly slow this means of creating a sparse -matrix. Furthermore, it is possible to create a sparse matrix with -too much storage, so having @var{nz} above equaling 6 is also valid. -The disadvantage is that the matrix occupies more memory than strictly -needed. +is perfectly valid. However, it is a very bad idea because as each new +element is added to the sparse matrix the matrix needs to request more +space and reallocate memory. This is an expensive operation, that will +significantly slow this means of creating a sparse matrix. Furthermore, +it is possible to create a sparse matrix with too much storage, so having +@var{nz} greater than 4 is also valid. The disadvantage is that the matrix +occupies more memory than strictly needed. -It is not always easy to know the number of non-zero elements prior -to filling a matrix. For this reason the additional storage for the -sparse matrix can be removed after its creation with the -@dfn{maybe_compress} function. Furthermore, the maybe_compress can -deallocate the unused storage, but it can equally remove zero elements +It is not always possible to know the number of non-zero elements prior +to filling a matrix. For this reason the additional unused storage of +a sparse matrix can be removed after its creation with the +@code{maybe_compress} function. In addition, @code{maybe_compress} can +deallocate the unused storage, but it can also remove zero elements from the matrix. The removal of zero elements from the matrix is -controlled by setting the argument of the @dfn{maybe_compress} function -to be @samp{true}. However, the cost of removing the zeros is high because it -implies resorting the elements. Therefore, if possible it is better -is the user doesn't add the zeros in the first place. An example of -the use of @dfn{maybe_compress} is +controlled by setting the argument of the @code{maybe_compress} function +to be @code{true}. However, the cost of removing the zeros is high because it +implies re-sorting the elements. If possible, it is better +if the user does not add the unnecessary zeros in the first place. +An example of the use of @code{maybe_compress} is @example @group - int nz = 6, nr = 3, nc = 4; +int nz = 6, nr = 3, nc = 4; - SparseMatrix sm1 (nr, nc, nz); - sm1(0,0) = 1; sm1(0,1) = 2; sm1(1,3) = 3; sm1(2,3) = 4; - sm1.maybe_compress (); // No zero elements were added +SparseMatrix sm1 (nr, nc, nz); +sm1(0,0) = 1; sm1(0,1) = 2; sm1(1,3) = 3; sm1(2,3) = 4; +sm1.maybe_compress (); // No zero elements were added - SparseMatrix sm2 (nr, nc, nz); - sm2(0,0) = 1; sm2(0,1) = 2; sm(0,2) = 0; sm(1,2) = 0; - sm1(1,3) = 3; sm1(2,3) = 4; - sm2.maybe_compress (true); // Zero elements were added +SparseMatrix sm2 (nr, nc, nz); +sm2(0,0) = 1; sm2(0,1) = 2; sm(0,2) = 0; sm(1,2) = 0; +sm1(1,3) = 3; sm1(2,3) = 4; +sm2.maybe_compress (true); // Zero elements were added @end group @end example -The use of the @dfn{maybe_compress} function should be avoided if -possible, as it will slow the creation of the matrices. +The use of the @code{maybe_compress} function should be avoided if +possible as it will slow the creation of the matrix. A third means of creating a sparse matrix is to work directly with the data in compressed row format. An example of this technique might be -@c Note the @verbatim environment is a relatively new addition to Texinfo. -@c Therefore use the @example environment and replace @, with @@, -@c { with @{, etc - @example octave_value arg; @dots{} -int nz = 6, nr = 3, nc = 4; // Assume we know the max no nz +int nz = 6, nr = 3, nc = 4; // Assume we know the max # nz SparseMatrix sm (nr, nc, nz); Matrix m = arg.matrix_value (); @@ -757,12 +806,11 @@ @} sm.cidx(j+1) = ii; @} -sm.maybe_compress (); // If don't know a-priori - // the final no of nz. +sm.maybe_compress (); // If don't know a-priori the final # of nz. @end example @noindent -which is probably the most efficient means of creating the sparse matrix. +which is probably the most efficient means of creating a sparse matrix. Finally, it might sometimes arise that the amount of storage initially created is insufficient to completely store the sparse matrix. Therefore, @@ -772,7 +820,7 @@ @example octave_value arg; @dots{} -int nz = 6, nr = 3, nc = 4; // Assume we know the max no nz +int nz = 6, nr = 3, nc = 4; // Assume we know the max # nz SparseMatrix sm (nr, nc, nz); Matrix m = arg.matrix_value (); @@ -797,23 +845,22 @@ @} sm.cidx(j+1) = ii; @} -sm.maybe_mutate (); // If don't know a-priori - // the final no of nz. +sm.maybe_mutate (); // If don't know a-priori the final # of nz. @end example Note that both increasing and decreasing the number of non-zero elements in -a sparse matrix is expensive, as it involves memory reallocation. Also as -parts of the matrix, though not its entirety, exist as the old and new copy -at the same time, additional memory is needed. Therefore if possible this +a sparse matrix is expensive as it involves memory reallocation. Also as +parts of the matrix, though not its entirety, exist as old and new copies +at the same time, additional memory is needed. Therefore, if possible this should be avoided. @node Using Sparse Matrices in Oct-Files @subsubsection Using Sparse Matrices in Oct-Files Most of the same operators and functions on sparse matrices that are -available from the Octave are equally available with oct-files. +available from the Octave command line are also available within oct-files. The basic means of extracting a sparse matrix from an @code{octave_value} -and returning them as an @code{octave_value}, can be seen in the +and returning it as an @code{octave_value}, can be seen in the following example. @example @@ -831,20 +878,19 @@ @end group @end example -The conversion to an octave-value is handled by the sparse +The conversion to an @code{octave_value} is handled by the sparse @code{octave_value} constructors, and so no special care is needed. @node Accessing Global Variables in Oct-Files @subsection Accessing Global Variables in Oct-Files Global variables allow variables in the global scope to be -accessed. Global variables can easily be accessed with oct-files using -the support functions @code{get_global_value} and -@code{set_global_value}. @code{get_global_value} takes two arguments, -the first is a string representing the variable name to obtain. The -second argument is a boolean argument specifying what to do in the case -that no global variable of the desired name is found. An example of the -use of these two functions is +accessed. Global variables can be accessed within oct-files by using +the support functions @code{get_global_value} and @code{set_global_value}. +@code{get_global_value} takes two arguments, the first is a string representing +the variable name to obtain. The second argument is a boolean argument +specifying what to do if no global variable of the desired name is found. +An example of the use of these two functions is @example @EXAMPLEFILE(globaldemo.cc) @@ -868,9 +914,9 @@ @node Calling Octave Functions from Oct-Files @subsection Calling Octave Functions from Oct-Files -There is often a need to be able to call another octave function from -within an oct-file, and there are many examples of such within octave -itself. For example the @code{quad} function is an oct-file that +There is often a need to be able to call another Octave function from +within an oct-file, and there are many examples of such within Octave +itself. For example, the @code{quad} function is an oct-file that calculates the definite integral by quadrature over a user supplied function. @@ -894,8 +940,8 @@ @EXAMPLEFILE(funcdemo.cc) @end example -The first argument to this demonstration is the user supplied function -and the following arguments are all passed to the user function. +The first argument to this demonstration is the user-supplied function +and the remaining arguments are all passed to the user function. @example @group @@ -912,40 +958,41 @@ @end group @end example -When the user function is passed as a string, the treatment of the -function is different. In some cases it is necessary to always have the +When the user function is passed as a string the treatment of the +function is different. In some cases it is necessary to have the user supplied function as an @code{octave_function} object. In that -case the string argument can be used to create a temporary function like +case the string argument can be used to create a temporary function +as demonstrated below. @example @group std::octave fcn_name = unique_symbol_name ("__fcn__"); -std::string fname = "function y = "; -fname.append (fcn_name); -fname.append ("(x) y = "); +std::string fcode = "function y = "; +fcode.append (fcn_name); +fcode.append ("(x) y = "); fcn = extract_function (args(0), "funcdemo", fcn_name, - fname, "; endfunction"); + fcode, "; endfunction"); @dots{} if (fcn_name.length ()) clear_function (fcn_name); @end group @end example -There are two important things to know in this case. The number of input -arguments to the user function is fixed, and in the above is a single -argument, and secondly to avoid leaving the temporary function in the -Octave symbol table it should be cleared after use. +There are two important things to know in this case. First, the number of +input arguments to the user function is fixed, and in the above example is +a single argument. Second, to avoid leaving the temporary function in the +Octave symbol table it should be cleared after use. Also, by convention +internal function names begin and end with the character sequence @samp{__}. @node Calling External Code from Oct-Files @subsection Calling External Code from Oct-Files Linking external C code to Octave is relatively simple, as the C functions can easily be called directly from C++. One possible issue is -the declarations of the external C functions might need to be explicitly +that the declarations of the external C functions may need to be explicitly defined as C functions to the compiler. If the declarations of the -external C functions are in the header @code{foo.h}, then the manner in -which to ensure that the C++ compiler treats these declarations as C -code is +external C functions are in the header @file{foo.h}, then the tactic to +ensure that the C++ compiler treats these declarations as C code is @example @group @@ -960,10 +1007,10 @@ @end group @end example -Calling Fortran code however can pose some difficulties. This is due to -differences in the manner in compilers treat the linking of Fortran code -with C or C++ code. Octave supplies a number of macros that allow -consistent behavior across a number of compilers. +Calling Fortran code, however, can pose more difficulties. This is due to +differences in the manner in which compilers treat the linking of Fortran code +with C or C++ code. Octave supplies a number of macros that allow consistent +behavior across a number of compilers. The underlying Fortran code should use the @code{XSTOPX} function to replace the Fortran @code{STOP} function. @code{XSTOPX} uses the Octave @@ -971,15 +1018,15 @@ explicitly. Note that Octave supplies its own replacement @sc{blas} @code{XERBLA} function, which uses @code{XSTOPX}. -If the underlying code calls @code{XSTOPX}, then the @w{@code{F77_XFCN}} +If the code calls @code{XSTOPX}, then the @w{@code{F77_XFCN}} macro should be used to call the underlying Fortran function. The Fortran exception state can then be checked with the global variable @code{f77_exception_encountered}. If @code{XSTOPX} will not be called, then the @w{@code{F77_FCN}} macro should be used instead to call the Fortran code. -There is no harm in using @w{@code{F77_XFCN}} in all cases, except that for -Fortran code that is short running and executes a large number of times, +There is no great harm in using @w{@code{F77_XFCN}} in all cases, except that +for Fortran code that is short running and executes a large number of times, there is potentially an overhead in doing so. However, if @w{@code{F77_FCN}} is used with code that calls @code{XSTOP}, Octave can generate a segmentation fault. @@ -1000,18 +1047,18 @@ This example demonstrates most of the features needed to link to an external Fortran function, including passing arrays and strings, as well -as exception handling. An example of the behavior of this function is +as exception handling. Both the Fortran and C++ files need to be compiled +in order for the example to work. @example @group +mkoctfile fortdemo.cc fortsub.f [b, s] = fortdemo (1:3) @result{} b = 1.00000 0.50000 0.33333 s = There are 3 values in the input vector [b, s] = fortdemo (0:3) -error: fortsub:divide by zero -error: exception encountered in Fortran subroutine fortsub_ -error: fortdemo: error in Fortran +error: fortdemo: fortsub: divide by zero @end group @end example @@ -1019,7 +1066,7 @@ @subsection Allocating Local Memory in Oct-Files Allocating memory within an oct-file might seem easy as the C++ -new/delete operators can be used. However, in that case care must be +new/delete operators can be used. However, in that case great care must be taken to avoid memory leaks. The preferred manner in which to allocate memory for use locally is to use the @w{@code{OCTAVE_LOCAL_BUFFER}} macro. An example of its use is @@ -1032,27 +1079,32 @@ that returns a pointer @code{tmp} of type @code{double *} of length @code{len}. +In this case Octave itself will worry about reference counting and variable +scope and will properly free memory without programmer intervention. + @node Input Parameter Checking in Oct-Files @subsection Input Parameter Checking in Oct-Files -As oct-files are compiled functions they have the possibility of causing -Octave to abort abnormally. It is therefore important that -each and every function has the minimum of parameter -checking needed to ensure that Octave behaves well. +As oct-files are compiled functions they open up the possibility of +crashing Octave through careless function calls or memory faults. +It is quite important that each and every function have a sufficient level +of parameter checking to ensure that Octave behaves well. The minimum requirement, as previously discussed, is to check the number -of input arguments before using them to avoid referencing a non existent -argument. However, it some case this might not be sufficient as the -underlying code imposes further constraints. For example an external +of input arguments before using them to avoid referencing a non-existent +argument. However, in some cases this might not be sufficient as the +underlying code imposes further constraints. For example, an external function call might be undefined if the input arguments are not -integers, or if one of the arguments is zero. Therefore, oct-files often -need additional input parameter checking. +integers, or if one of the arguments is zero, or if the input is complex +and a real value was expected. Therefore, oct-files often need additional +input parameter checking. -There are several functions within Octave that might be useful for the +There are several functions within Octave that can be useful for the purposes of parameter checking. These include the methods of the -octave_value class like @code{is_real_matrix}, etc., but equally include -more specialized functions. Some of the more common ones are -demonstrated in the following example. +octave_value class like @code{is_real_matrix}, @code{is_numeric_type}, etc. +Often, with a knowledge of the Octave m-file language, you can guess at what +the corresponding C++ routine will. In addition there are some more +specialized input validation functions of which a few are demonstrated below. @example @EXAMPLEFILE(paramdemo.cc) @@ -1075,10 +1127,10 @@ @subsection Exception and Error Handling in Oct-Files Another important feature of Octave is its ability to react to the user -typing @kbd{Control-C} even during calculations. This ability is based on the +typing @key{Control-C} even during calculations. This ability is based on the C++ exception handler, where memory allocated by the C++ new/delete methods are automatically released when the exception is treated. When -writing an oct-file, to allow Octave to treat the user typing @kbd{Control-C}, +writing an oct-file, to allow Octave to treat the user typing @key{Control-C}, the @w{@code{OCTAVE_QUIT}} macro is supplied. For example: @example @@ -1092,9 +1144,9 @@ @end example The presence of the @w{@code{OCTAVE_QUIT}} macro in the inner loop allows -Octave to treat the user request with the @kbd{Control-C}. Without this macro, +Octave to treat the user request with the @key{Control-C}. Without this macro, the user must either wait for the function to return before the interrupt is -processed, or press @kbd{Control-C} three times to force Octave to exit. +processed, or press @key{Control-C} three times to force Octave to exit. The @w{@code{OCTAVE_QUIT}} macro does impose a very small speed penalty, and so for loops that are known to be small it might not make sense to include @@ -1122,7 +1174,7 @@ The Octave unwind_protect mechanism (@ref{The unwind_protect Statement}) can also be used in oct-files. In conjunction with the exception handling of Octave, it is important to enforce that certain code is run -to allow variables, etc. to be restored even if an exception occurs. An +to allow variables, etc.@: to be restored even if an exception occurs. An example of the use of this mechanism is @example @@ -1141,7 +1193,7 @@ @end group @end example -The division by zero (and in fact all warnings) is disabled in the +The warning for division by zero (and in fact all warnings) are disabled in the @code{unwinddemo} function. @node Documentation and Test of Oct-Files @@ -1154,9 +1206,9 @@ help strings within oct-files. The major issue is that the help string will typically be longer than a -single line of text, and so the formatting of long help strings need to -be taken into account. There are several manners in which to treat this -issue, but the most common is illustrated in the following example, +single line of text, and so the formatting of long help strings needs to +be taken into account. There are several possible solutions, but the most +common is illustrated in the following example, @example @group @@ -1173,32 +1225,29 @@ @end example @noindent -where, as can be seen, end line of text within the help string is -terminated by @code{\n\} which is an embedded new-line in the string -together with a C++ string continuation character. Note that the final -@code{\} must be the last character on the line. +where, as can be seen, each line of text is terminated by @code{\n\} +which is an embedded new-line in the string together with a C++ string +continuation character. Note that the final @code{\} must be the last +character on the line. -Octave also includes the ability to embed the test and demonstration +Octave also includes the ability to embed test and demonstration code for a function within the code itself (@ref{Test and Demo Functions}). This can be used from within oct-files (or in fact any file) with -certain provisos. Firstly, the test and demo functions of Octave look -for a @code{%!} as the first characters on a new-line to identify test -and demonstration code. This is equally a requirement for -oct-files. Furthermore the test and demonstration code must be included -in a comment block of the compiled code to avoid it being interpreted by -the compiler. Finally, the Octave test and demonstration code must have -access to the source code of the oct-file and not just the compiled code -as the tests are stripped from the compiled code. An example in an -oct-file might be +certain provisos. First, the test and demo functions of Octave look +for @code{%!} as the first two characters of a line to identify test +and demonstration code. This is a requirement for oct-files as well. +In addition, the test and demonstration code must be wrapped in a comment +block to avoid it being interpreted by the compiler. Finally, the Octave +test and demonstration code must have access to the original source code +of the oct-file and not just the compiled code as the tests are stripped +from the compiled code. An example in an oct-file might be @example @group /* - +%!assert (sin ([1,2]), [sin(1),sin(2)]) %!error (sin ()) %!error (sin (1,1)) -%!assert (sin ([1,2]),[sin(1),sin(2)]) - */ @end group @end example @@ -1215,14 +1264,14 @@ Octave includes an interface to allow legacy mex-files to be compiled and used with Octave. This interface can also be used to share code -between Octave and @sc{matlab} users. However, as mex-files expose the +between Octave and @sc{matlab} users. However, as mex-files expose @sc{matlab}'s internal API, and the internal structure of Octave is different, a mex-file can never have the same performance in Octave as -the equivalent oct-file. In particular to support the manner in which -mex-files access the variables passed to mex functions, there are a -significant number of additional copies of memory when calling or -returning from a mex function. For this reason, new code should be -written using the oct-file interface discussed above if possible. +the equivalent oct-file. In particular, to support the manner in which +variables are passed to mex functions there are a significant number of +additional copies of memory blocks when calling or returning from a +mex-file function. For this reason, it is recommended that any new code +be written with the oct-file interface previously discussed. @menu * Getting Started with Mex-Files:: @@ -1239,59 +1288,73 @@ @subsection Getting Started with Mex-Files The basic command to build a mex-file is either @code{mkoctfile --mex} -or @code{mex}. The first can either be used from within Octave or from +or @code{mex}. The first command can be used either from within Octave or from the command line. However, to avoid issues with @sc{matlab}'s own @code{mex} command, the use of the command @code{mex} is limited to within Octave. +Compiled mex-files have the extension @file{.mex}. @DOCSTRING(mex) @DOCSTRING(mexext) -One important difference with the use of @code{mex} between @sc{matlab} and -Octave is that the header file "matrix.h" is implicitly included through -the inclusion of "mex.h". This is to avoid a conflict with the Octave -file "Matrix.h" with operating systems and compilers that don't -distinguish between filenames in upper and lower case - -Consider the short example: +Consider the following short example: @example @group -@EXAMPLEFILE(firstmexdemo.c) +@EXAMPLEFILE(myhello.c) @end group @end example -This simple example demonstrates the basics of writing a mex-file. The -entry point into the mex-file is defined by @code{mexFunction}. Note -that the function name is not explicitly included in the +The first line @code{#include "mex.h"} makes available all of the definitions +necessary for a mex-file. One important difference between Octave and +@sc{matlab} is that the header file @code{"matrix.h"} is implicitly included +through the inclusion of @code{"mex.h"}. This is necessary to avoid a conflict +with the Octave file @code{"Matrix.h"} for operating systems and compilers that +don't distinguish between filenames in upper and lower case. + +The entry point into the mex-file is defined by @code{mexFunction}. The +function takes four arguments: + +@enumerate 1 +@item The number of return arguments (# of left-hand side args). + +@item An array of pointers to return arguments. + +@item The number of input arguments (# of right-hand side args). + +@item An array of pointers to input arguments. +@end enumerate + +Note that the function name definition is not explicitly included in @code{mexFunction} and so there can only be a single @code{mexFunction} -entry point per-file. Also the name of the function is determined by the -name of the mex-file itself. Therefore if the above function is in the -file @file{firstmexdemo.c}, it can be compiled with +entry point per file. Instead, the name of the function as seen in Octave is +determined by the name of the mex-file itself minus the extension. Therefore, +if the above function is in the file @file{myhello.c}, it can be compiled with @example -mkoctfile --mex firstmexdemo.c +mkoctfile --mex myhello.c @end example @noindent -which creates a file @file{firstmexdemo.mex}. The function can then be run -from Octave as +which creates a file @file{myhello.mex}. The function can then be run from +Octave as @example @group -firstmexdemo () -@result{} 1.2346 +myhello (1,2,3) +@result{} Hello, World! +@result{} I have 3 inputs and 0 outputs @end group @end example It should be noted that the mex-file contains no help string for the functions it contains. To document mex-files, there should exist an m-file in the same directory as the mex-file itself. Taking the above as -an example, we would therefore have a file @file{firstmexdemo.m} that might +an example, we would therefore have a file @file{myhello.m} that might contain the text @example -%FIRSTMEXDEMO Simple test of the functionality of a mex-file. +%MYHELLO Simple test of the functionality of a mex-file. @end example In this case, the function that will be executed within Octave will be @@ -1299,10 +1362,10 @@ m-file. This can also be useful to allow a sample implementation of the mex-file within the Octave language itself for testing purposes. -Although we cannot have multiple entry points into a single mex-file, -we can use the @code{mexFunctionName} function to determine what name +Although there cannot be multiple entry points in a single mex-file, +one can use the @code{mexFunctionName} function to determine what name the mex-file was called with. This can be used to alter the behavior of -the mex-file based on the function name. For example if +the mex-file based on the function name. For example, if @example @group @@ -1320,7 +1383,8 @@ @end group @end example -Then as can be seen by +@noindent +then as can be seen by @example @group @@ -1336,34 +1400,34 @@ the behavior of the mex-file can be altered depending on the functions name. -Allow the user should only include @code{mex.h} in their code, Octave +Although the user should only include @file{mex.h} in their code, Octave declares additional functions, typedefs, etc., available to the user to -write mex-files in the headers @code{mexproto.h} and @code{mxarray.h}. +write mex-files in the headers @file{mexproto.h} and @file{mxarray.h}. @node Working with Matrices and Arrays in Mex-Files @subsection Working with Matrices and Arrays in Mex-Files -The basic mex type of all variables is @code{mxArray}. All variables, -such as matrices, cell arrays or structures are all stored in this basic -type, and this type serves basically the same purpose as the -octave_value class in oct-files. That is it acts as a container for the +The basic mex type of all variables is @code{mxArray}. Any object, +such as a matrix, cell array, or structure is stored in this basic +type. As such, @code{mxArray} serves basically the same purpose as the +octave_value class in oct-files in that it acts as a container for the more specialized types. -The @code{mxArray} structure contains at a minimum, the variable it -represents name, its dimensions, its type and whether the variable is -real or complex. It can however contain a number of additional fields +The @code{mxArray} structure contains at a minimum, the name of the +variable it represents, its dimensions, its type, and whether the variable is +real or complex. It can also contain a number of additional fields depending on the type of the @code{mxArray}. There are a number of functions to create @code{mxArray} structures, including -@code{mxCreateCellArray}, @code{mxCreateSparse} and the generic -@code{mxCreateNumericArray}. +@code{mxCreateDoubleMatrix}, @code{mxCreateCellArray}, @code{mxCreateSparse}, +and the generic @code{mxCreateNumericArray}. -The basic functions to access the data contained in an array is -@code{mxGetPr}. As the mex interface assumes that the real and imaginary +The basic function to access the data contained in an array is +@code{mxGetPr}. As the mex interface assumes that real and imaginary parts of a complex array are stored separately, there is an equivalent -function @code{mxGetPi} that get the imaginary part. Both of these -functions are for use only with double precision matrices. There also -exists the generic function @code{mxGetData} and @code{mxGetImagData} -that perform the same operation on all matrix types. For example: +function @code{mxGetPi} that gets the imaginary part. Both of these +functions are only for use with double precision matrices. The generic +functions @code{mxGetData} and @code{mxGetImagData} perform the same operation +on all matrix types. For example: @example @group @@ -1372,27 +1436,25 @@ UINT32_T *pr; dims = (mwSize *) mxMalloc (2 * sizeof (mwSize)); -dims[0] = 2; -dims[1] = 2; +dims[0] = 2; dims[1] = 2; m = mxCreateNumericArray (2, dims, mxUINT32_CLASS, mxREAL); -pr = = (UINT32_T *) mxGetData (m); +pr = (UINT32_T *) mxGetData (m); @end group @end example There are also the functions @code{mxSetPr}, etc., that perform the -inverse, and set the data of an Array to use the block of memory pointed +inverse, and set the data of an array to use the block of memory pointed to by the argument of @code{mxSetPr}. -Note the type @code{mwSize} used above, and @code{mwIndex} are defined +Note the type @code{mwSize} used above, and also @code{mwIndex}, are defined as the native precision of the indexing in Octave on the platform on which the mex-file is built. This allows both 32- and 64-bit platforms -to support mex-files. @code{mwSize} is used to define array dimension -and maximum number or elements, while @code{mwIndex} is used to define +to support mex-files. @code{mwSize} is used to define array dimensions +and the maximum number or elements, while @code{mwIndex} is used to define indexing into arrays. -An example that demonstration how to work with arbitrary real or complex -double precision arrays is given by the file @file{mypow2.c} as given -below. +An example that demonstrates how to work with arbitrary real or complex +double precision arrays is given by the file @file{mypow2.c} shown below. @example @EXAMPLEFILE(mypow2.c) @@ -1409,12 +1471,11 @@ @end group @end example - The example above uses the functions @code{mxGetDimensions}, @code{mxGetNumberOfElements}, and @code{mxGetNumberOfDimensions} to work with the dimensions of multi-dimensional arrays. The functions @code{mxGetM}, and @code{mxGetN} are also available to find the number -of rows and columns in a matrix. +of rows and columns in a 2-D matrix. @node Character Strings in Mex-Files @subsection Character Strings in Mex-Files @@ -1422,8 +1483,8 @@ As mex-files do not make the distinction between single and double quoted strings within Octave, there is perhaps less complexity in the use of strings and character matrices in mex-files. An example of their -use, that parallels the demo in @file{stringdemo.cc}, is given in the -file @file{mystring.c}, as seen below. +use that parallels the demo in @file{stringdemo.cc} is given in the +file @file{mystring.c}, as shown below. @example @EXAMPLEFILE(mystring.c) @@ -1450,10 +1511,10 @@ @node Cell Arrays with Mex-Files @subsection Cell Arrays with Mex-Files -We can perform exactly the same operations in Cell arrays in mex-files -as we can in oct-files. An example that reduplicates the functional of -the @file{celldemo.cc} oct-file in a mex-file is given by -@file{mycell.c} as below +One can perform exactly the same operations on Cell arrays in mex-files +as in oct-files. An example that reduplicates the function of +the @file{celldemo.cc} oct-file in a mex-file is given by @file{mycell.c} +as shown below. @example @group @@ -1462,8 +1523,7 @@ @end example @noindent -which as can be seen below has exactly the same behavior as the oct-file -version. +The output is identical to the oct-file version as well. @example @group @@ -1480,8 +1540,8 @@ Note in the example the use of the @code{mxDuplicateArray} function. This is needed as the @code{mxArray} pointer returned by @code{mxGetCell} -might be deallocated. The inverse function to @code{mxGetCell} is -@code{mcSetCell} and is defined as +might be deallocated. The inverse function to @code{mxGetCell}, used for +setting Cell values, is @code{mxSetCell} and is defined as @example void mxSetCell (mxArray *ptr, int idx, mxArray *val); @@ -1500,7 +1560,7 @@ @subsection Structures with Mex-Files The basic function to create a structure in a mex-file is -@code{mxCreateStructMatrix}, which creates a structure array with a two +@code{mxCreateStructMatrix} which creates a structure array with a two dimensional matrix, or @code{mxCreateStructArray}. @example @@ -1514,7 +1574,7 @@ @end group @end example -Accessing the fields of the structure can then be performed with the +Accessing the fields of the structure can then be performed with @code{mxGetField} and @code{mxSetField} or alternatively with the @code{mxGetFieldByNumber} and @code{mxSetFieldByNumber} functions. @@ -1534,11 +1594,11 @@ A difference between the oct-file interface to structures and the mex-file version is that the functions to operate on structures in mex-files directly include an @code{index} over the elements of the -arrays of elements per @code{field}. Whereas the oct-file structure +arrays of elements per @code{field}; Whereas, the oct-file structure includes a Cell Array per field of the structure. -An example that demonstrates the use of structures in mex-file can be -found in the file @file{mystruct.c}, as seen below +An example that demonstrates the use of structures in a mex-file can be +found in the file @file{mystruct.c} shown below. @example @EXAMPLEFILE(mystruct.c) @@ -1585,10 +1645,9 @@ matrices are required to be two-dimensional. The only difference is that the real and imaginary parts of the matrix are stored separately. -The mex-file interface, as well as using @code{mxGetM}, @code{mxGetN}, +The mex-file interface, in addition to using @code{mxGetM}, @code{mxGetN}, @code{mxSetM}, @code{mxSetN}, @code{mxGetPr}, @code{mxGetPi}, -@code{mxSetPr} and @code{mxSetPi}, the mex-file interface supplies the -functions +@code{mxSetPr}, and @code{mxSetPi}, also supplies the following functions. @example @group @@ -1609,7 +1668,7 @@ additional value than the number of columns in the sparse matrix. The difference between consecutive values of the array returned by @code{mxGetJc} define the number of non-zero elements in each column of -the sparse matrix. Therefore +the sparse matrix. Therefore, @example @group @@ -1629,7 +1688,7 @@ only contain the non-zero values of the matrix, we also need a pointer to the rows of the non-zero elements, and this is given by @code{mxGetIr}. A complete example of the use of sparse matrices in -mex-files is given by the file @file{mysparse.c} as seen below +mex-files is given by the file @file{mysparse.c} shown below. @example @EXAMPLEFILE(mysparse.c) @@ -1638,9 +1697,9 @@ @node Calling Other Functions in Mex-Files @subsection Calling Other Functions in Mex-Files -It is also possible call other Octave functions from within a mex-file -using @code{mexCallMATLAB}. An example of the use of -@code{mexCallMATLAB} can be see in the example below +It is possible to call other Octave functions from within a mex-file +using @code{mexCallMATLAB}. An example of the use of @code{mexCallMATLAB} +can be see in the example below. @example @EXAMPLEFILE(myfeval.c) @@ -1671,9 +1730,9 @@ @node Standalone Programs @section Standalone Programs -The libraries Octave itself uses, can be utilized in standalone +The libraries Octave itself uses can be utilized in standalone applications. These applications then have access, for example, to the -array and matrix classes as well as to all the Octave algorithms. The +array and matrix classes, as well as to all of the Octave algorithms. The following C++ program, uses class Matrix from @file{liboctave.a} or @file{liboctave.so}. @@ -1684,7 +1743,7 @@ @end example @noindent -mkoctfile can then be used to build a standalone application with a +mkoctfile can be used to build a standalone application with a command like @example @@ -1698,10 +1757,10 @@ @end group @end example -Note that the application @code{hello} will be dynamically linked -against the octave libraries and any octave support libraries. The above +Note that the application @code{standalone} will be dynamically linked +against the Octave libraries and any Octave support libraries. The above allows the Octave math libraries to be used by an application. It does -not however allow the script files, oct-files or builtin functions of +not, however, allow the script files, oct-files, or builtin functions of Octave to be used by the application. To do that the Octave interpreter needs to be initialized first. An example of how to do this can then be seen in the code @@ -1713,7 +1772,7 @@ @end example @noindent -which is compiled and run as before as a standalone application with +which, as before, is compiled and run as a standalone application with @example @group
--- a/doc/interpreter/intro.txi +++ b/doc/interpreter/intro.txi @@ -617,7 +617,7 @@ The function described is written in a language like C++, C, or Fortran. On systems that support dynamic linking of user-supplied functions, it may be automatically linked while Octave is running, but only if it is -needed. @xref{Dynamically Linked Functions}. +needed. @xref{External Code Interface}. @item Mapping Function @cindex mapping function
--- a/doc/interpreter/octave.texi +++ b/doc/interpreter/octave.texi @@ -180,7 +180,7 @@ * System Utilities:: * Java Interface:: * Packages:: -* Dynamically Linked Functions:: +* External Code Interface:: * Test and Demo Functions:: * Tips and Standards:: * Contributing Guidelines:: @@ -792,7 +792,7 @@ * The INDEX File:: * PKG_ADD and PKG_DEL Directives:: -Dynamically Linked Functions +External Code Interface * Oct-Files:: * Mex-Files:: @@ -943,7 +943,7 @@ @c ------------------------------------------------------------------------ @c Appendices start here. -@include dynamic.texi +@include external.texi @include testfun.texi @include tips.texi @include contrib.texi
--- a/doc/interpreter/sparse.txi +++ b/doc/interpreter/sparse.txi @@ -308,7 +308,7 @@ The above problem of memory reallocation can be avoided in oct-files. However, the construction of a sparse matrix from an oct-file is more complex than can be discussed here, and -you are referred to chapter @ref{Dynamically Linked Functions}, to have +you are referred to chapter @ref{External Code Interface}, to have a full description of the techniques involved. @node Information
--- a/examples/Makefile.am +++ b/examples/Makefile.am @@ -34,14 +34,13 @@ addtwomatrices.cc \ celldemo.cc \ embedded.cc \ - firstmexdemo.c \ fortdemo.cc \ fortsub.f \ funcdemo.cc \ globaldemo.cc \ - hello.cc \ helloworld.cc \ make_int.cc \ + mex_demo.c \ mycell.c \ myfeval.c \ myfevalf.f \ @@ -53,6 +52,7 @@ mysparse.c \ mystring.c \ mystruct.c \ + oct_demo.cc \ oregonator.cc \ oregonator.m \ paramdemo.cc \
--- a/examples/addtwomatrices.cc +++ b/examples/addtwomatrices.cc @@ -3,6 +3,7 @@ DEFUN_DLD (addtwomatrices, args, , "Add A to B") { int nargin = args.length (); + if (nargin != 2) print_usage (); else @@ -12,5 +13,6 @@ if (! error_state) return octave_value (A + B); } + return octave_value_list (); }
--- a/examples/celldemo.cc +++ b/examples/celldemo.cc @@ -10,10 +10,13 @@ print_usage (); else { - Cell c = args (0).cell_value (); + Cell c = args(0).cell_value (); if (! error_state) - for (octave_idx_type i = 0; i < c.nelem (); i++) - retval(i) = c.elem (i); + for (octave_idx_type i = 0; i < c.numel (); i++) + { + retval(i) = c(i); // using operator syntax + //retval(i) = c.elem (i); // using method syntax + } } return retval;
--- a/examples/embedded.cc +++ b/examples/embedded.cc @@ -20,7 +20,6 @@ octave_value_list out = feval ("gcd", in, 1); - if (!error_state && out.length () > 0) std::cout << "GCD of [" << in(0).int_value ()
--- a/examples/fortdemo.cc +++ b/examples/fortdemo.cc @@ -9,10 +9,11 @@ F77_CHAR_ARG_LEN_DECL); } -DEFUN_DLD (fortdemo , args , , "Fortran Demo.") +DEFUN_DLD (fortdemo, args, , "Fortran Demo") { octave_value_list retval; int nargin = args.length (); + if (nargin != 1) print_usage (); else @@ -21,7 +22,7 @@ if (! error_state) { double *av = a.fortran_vec (); - octave_idx_type na = a.nelem (); + octave_idx_type na = a.numel (); OCTAVE_LOCAL_BUFFER (char, ctmp, 128); F77_XFCN (fortsub, FORTSUB, (na, av, ctmp
--- a/examples/funcdemo.cc +++ b/examples/funcdemo.cc @@ -3,8 +3,8 @@ DEFUN_DLD (funcdemo, args, nargout, "Function Demo") { + octave_value_list retval; int nargin = args.length (); - octave_value_list retval; if (nargin < 2) print_usage (); @@ -12,9 +12,8 @@ { octave_value_list newargs; for (octave_idx_type i = nargin - 1; i > 0; i--) - newargs (i - 1) = args(i); - if (args(0).is_function_handle () - || args(0).is_inline_function ()) + newargs(i-1) = args(i); + if (args(0).is_function_handle () || args(0).is_inline_function ()) { octave_function *fcn = args(0).function_value (); if (! error_state) @@ -22,13 +21,12 @@ } else if (args(0).is_string ()) { - std::string fcn = args (0).string_value (); + std::string fcn = args(0).string_value (); if (! error_state) retval = feval (fcn, newargs, nargout); } else - error ("funcdemo: expected string,", - " inline or function handle"); + error ("funcdemo: INPUT must be string, inline, or function handle"); } return retval; }
--- a/examples/globaldemo.cc +++ b/examples/globaldemo.cc @@ -1,9 +1,9 @@ #include <octave/oct.h> -DEFUN_DLD (globaldemo, args, , "Global demo.") +DEFUN_DLD (globaldemo, args, , "Global Demo") { + octave_value retval; int nargin = args.length (); - octave_value retval; if (nargin != 1) print_usage ();
--- a/examples/helloworld.cc +++ b/examples/helloworld.cc @@ -4,8 +4,10 @@ "Hello World Help String") { int nargin = args.length (); - octave_stdout << "Hello World has " << nargin - << " input arguments and " - << nargout << " output arguments.\n"; + + octave_stdout << "Hello World has " + << nargin << " input arguments and " + << nargout << " output arguments.\n"; + return octave_value_list (); }
rename from examples/firstmexdemo.c rename to examples/mex_demo.c --- a/examples/firstmexdemo.c +++ b/examples/mex_demo.c @@ -1,11 +1,58 @@ +// mex_demo.c -- example of a dynamically linked function for Octave. + +// To use this file, your version of Octave must support dynamic +// linking. To find out if it does, type the command +// +// octave_config_info ("ENABLE_DYNAMIC_LINKING") +// +// at the Octave prompt. Support for dynamic linking is included if +// this expression returns the string "yes". +// +// To compile this file, type the command +// +// mkoctfile mex_demo.c +// +// from within Octave or from the shell prompt. This will create a file +// called mex_demo.mex that can be loaded by Octave. To test the mex_demo.mex +// file, start Octave and type the command +// +// [d] = mex_demo ("easy as", 1, 2, 3) +// +// at the Octave prompt. Octave should respond by printing +// +// Hello, world! +// I have 4 inputs and 1 output +// d = 1.2346 + +// Additional samples of code are in the examples directory of the Octave +// distribution. See also the chapter External Code Interface in the +// documentation. + #include "mex.h" +// Every user function should include "mex.h" which imports the basic set of +// function prototypes necessary for dynamically linked functions. In +// particular, it will declare mexFunction which is used by every function +// which will be visible to Octave. A mexFunction is visible in Octave under +// the name of the source code file without the extension. + +// The four arguments to mexFunction are: +// 1) The number of return arguments (# of left-hand side args). +// 2) An array of pointers to return arguments. +// 3) The number of input arguments (# of right-hand side args). +// 4) An array of pointers to input arguments. + void -mexFunction (int nlhs, mxArray *plhs[], int nrhs, - const mxArray *prhs[]) +mexFunction (int nlhs, mxArray *plhs[], + int nrhs, const mxArray *prhs[]) { + mexPrintf ("Hello, World!\n"); + + mexPrintf ("I have %d inputs and %d outputs\n", nrhs, nlhs); + mxArray *v = mxCreateDoubleMatrix (1, 1, mxREAL); double *data = mxGetPr (v); *data = 1.23456789; + plhs[0] = v; }
--- a/examples/mycell.c +++ b/examples/mycell.c @@ -1,14 +1,14 @@ #include "mex.h" void -mexFunction (int nlhs, mxArray* plhs[], int nrhs, - const mxArray* prhs[]) +mexFunction (int nlhs, mxArray* plhs[], + int nrhs, const mxArray* prhs[]) { mwSize n; mwIndex i; if (nrhs != 1 || ! mxIsCell (prhs[0])) - mexErrMsgTxt ("expects cell"); + mexErrMsgTxt ("ARG1 must be a cell"); n = mxGetNumberOfElements (prhs[0]); n = (n > nlhs ? nlhs : n);
--- a/examples/myfeval.c +++ b/examples/myfeval.c @@ -1,24 +1,23 @@ #include "mex.h" void -mexFunction (int nlhs, mxArray* plhs[], int nrhs, - const mxArray* prhs[]) +mexFunction (int nlhs, mxArray* plhs[], + int nrhs, const mxArray* prhs[]) { char *str; mexPrintf ("Hello, World!\n"); - mexPrintf ("I have %d inputs and %d outputs\n", nrhs, - nlhs); + mexPrintf ("I have %d inputs and %d outputs\n", nrhs, nlhs); if (nrhs < 1 || ! mxIsString (prhs[0])) - mexErrMsgTxt ("function name expected"); + mexErrMsgTxt ("ARG1 must be a function name"); str = mxArrayToString (prhs[0]); mexPrintf ("I'm going to call the function %s\n", str); - mexCallMATLAB (nlhs, plhs, nrhs-1, prhs+1, str); + mexCallMATLAB (nlhs, plhs, nrhs-1, (mxArray*)prhs+1, str); mxFree (str); }
--- a/examples/myfunc.c +++ b/examples/myfunc.c @@ -1,13 +1,15 @@ #include "mex.h" void -mexFunction (int nlhs, mxArray *plhs[], int nrhs, - const mxArray *prhs[]) +mexFunction (int nlhs, mxArray *plhs[], + int nrhs, const mxArray *prhs[]) { const char *nm; + nm = mexFunctionName (); mexPrintf ("You called function: %s\n", nm); if (strcmp (nm, "myfunc") == 0) mexPrintf ("This is the principal function\n", nm); + return; }
--- a/examples/myhello.c +++ b/examples/myhello.c @@ -1,13 +1,10 @@ #include "mex.h" void -mexFunction (int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[]) +mexFunction (int nlhs, mxArray *plhs[], + int nrhs, const mxArray *prhs[]) { - mxArray *v = mxCreateDoubleMatrix (1, 1, mxREAL); + mexPrintf ("Hello, World!\n"); - double *data = mxGetPr (v); - - *data = 1.23456789; - - plhs[0] = v; + mexPrintf ("I have %d inputs and %d outputs\n", nrhs, nlhs); }
--- a/examples/mypow2.c +++ b/examples/mypow2.c @@ -1,21 +1,20 @@ #include "mex.h" void -mexFunction (int nlhs, mxArray* plhs[], int nrhs, - const mxArray* prhs[]) +mexFunction (int nlhs, mxArray* plhs[], + int nrhs, const mxArray* prhs[]) { + mwSize n; mwIndex i; - mwSize n; double *vri, *vro; if (nrhs != 1 || ! mxIsNumeric (prhs[0])) - mexErrMsgTxt ("expects matrix"); + mexErrMsgTxt ("ARG1 must be a matrix"); n = mxGetNumberOfElements (prhs[0]); - plhs[0] = (mxArray *) mxCreateNumericArray - (mxGetNumberOfDimensions (prhs[0]), - mxGetDimensions (prhs[0]), mxGetClassID (prhs[0]), - mxIsComplex (prhs[0])); + plhs[0] = mxCreateNumericArray + (mxGetNumberOfDimensions (prhs[0]), mxGetDimensions (prhs[0]), + mxGetClassID (prhs[0]), mxIsComplex (prhs[0])); vri = mxGetPr (prhs[0]); vro = mxGetPr (plhs[0]); @@ -27,13 +26,13 @@ for (i = 0; i < n; i++) { - vro [i] = vri [i] * vri [i] - vii [i] * vii [i]; - vio [i] = 2 * vri [i] * vii [i]; + vro[i] = vri[i] * vri[i] - vii[i] * vii[i]; + vio[i] = 2 * vri[i] * vii[i]; } } else { for (i = 0; i < n; i++) - vro [i] = vri [i] * vri [i]; + vro[i] = vri[i] * vri[i]; } }
--- a/examples/myprop.c +++ b/examples/myprop.c @@ -1,7 +1,8 @@ #include "mex.h" void -mexFunction (int nlhs, mxArray* plhs[], int nrhs, const mxArray* prhs[]) +mexFunction (int nlhs, mxArray* plhs[], + int nrhs, const mxArray* prhs[]) { double handle; char property[256]; @@ -21,5 +22,3 @@ if (mexSet (handle, property, mxDuplicateArray (prhs[2]))) mexErrMsgTxt ("failed to set property"); } - -
--- a/examples/myset.c +++ b/examples/myset.c @@ -1,7 +1,8 @@ #include "mex.h" void -mexFunction (int nlhs, mxArray* plhs[], int nrhs, const mxArray* prhs[]) +mexFunction (int nlhs, mxArray* plhs[], + int nrhs, const mxArray* prhs[]) { char *str; mxArray *v; @@ -16,7 +17,7 @@ if (v) { mexPrintf ("%s is a global variable with the following value:\n", str); - mexCallMATLAB (0, 0, 1, &v, "disp"); + mexCallMATLAB (0, NULL, 1, &v, "disp"); } v = mexGetArray (str, "caller"); @@ -24,7 +25,7 @@ if (v) { mexPrintf ("%s is a caller variable with the following value:\n", str); - mexCallMATLAB (0, 0, 1, &v, "disp"); + mexCallMATLAB (0, NULL, 1, &v, "disp"); } // WARNING!! Can't do this in MATLAB! Must copy variable first.
--- a/examples/mysparse.c +++ b/examples/mysparse.c @@ -1,10 +1,10 @@ #include "mex.h" void -mexFunction (int nlhs, mxArray *plhs[], int nrhs, - const mxArray *prhs[]) +mexFunction (int nlhs, mxArray *plhs[], + int nrhs, const mxArray *prhs[]) { - mwSize n, m, nz; + mwSize m, n, nz; mxArray *v; mwIndex i; double *pr, *pi; @@ -13,16 +13,15 @@ mwIndex *ir2, *jc2; if (nrhs != 1 || ! mxIsSparse (prhs[0])) - mexErrMsgTxt ("expects sparse matrix"); + mexErrMsgTxt ("ARG1 must be a sparse matrix"); - m = mxGetM (prhs [0]); - n = mxGetN (prhs [0]); - nz = mxGetNzmax (prhs [0]); + m = mxGetM (prhs[0]); + n = mxGetN (prhs[0]); + nz = mxGetNzmax (prhs[0]); if (mxIsComplex (prhs[0])) { - mexPrintf ("Matrix is %d-by-%d complex", - " sparse matrix", m, n); + mexPrintf ("Matrix is %d-by-%d complex sparse matrix", m, n); mexPrintf (" with %d elements\n", nz); pr = mxGetPr (prhs[0]); @@ -32,9 +31,9 @@ i = n; while (jc[i] == jc[i-1] && i != 0) i--; - mexPrintf ("last non-zero element (%d, %d) =", - ir[nz-1]+ 1, i); - mexPrintf (" (%g, %g)\n", pr[nz-1], pi[nz-1]); + + mexPrintf ("last non-zero element (%d, %d) = (%g, %g)\n", + ir[nz-1]+ 1, i, pr[nz-1], pi[nz-1]); v = mxCreateSparse (m, n, nz, mxCOMPLEX); pr2 = mxGetPr (v); @@ -57,8 +56,7 @@ else if (mxIsLogical (prhs[0])) { mxLogical *pbr, *pbr2; - mexPrintf ("Matrix is %d-by-%d logical", - " sparse matrix", m, n); + mexPrintf ("Matrix is %d-by-%d logical sparse matrix", m, n); mexPrintf (" with %d elements\n", nz); pbr = mxGetLogicals (prhs[0]); @@ -88,8 +86,7 @@ } else { - mexPrintf ("Matrix is %d-by-%d real", - " sparse matrix", m, n); + mexPrintf ("Matrix is %d-by-%d real sparse matrix", m, n); mexPrintf (" with %d elements\n", nz); pr = mxGetPr (prhs[0]); @@ -99,7 +96,7 @@ i = n; while (jc[i] == jc[i-1] && i != 0) i--; mexPrintf ("last non-zero element (%d, %d) = %g\n", - ir[nz-1]+ 1, i, pr[nz-1]); + ir[nz-1]+ 1, i, pr[nz-1]); v = mxCreateSparse (m, n, nz, mxREAL); pr2 = mxGetPr (v);
--- a/examples/mystring.c +++ b/examples/mystring.c @@ -2,25 +2,24 @@ #include "mex.h" void -mexFunction (int nlhs, mxArray *plhs[], int nrhs, - const mxArray *prhs[]) +mexFunction (int nlhs, mxArray *plhs[], + int nrhs, const mxArray *prhs[]) { + mwSize m, n; mwIndex i, j; - mwSize m, n; mxChar *pi, *po; if (nrhs != 1 || ! mxIsChar (prhs[0]) || mxGetNumberOfDimensions (prhs[0]) > 2) - mexErrMsgTxt ("expecting char matrix"); + mexErrMsgTxt ("ARG1 must be a char matrix"); m = mxGetM (prhs[0]); n = mxGetN (prhs[0]); pi = mxGetChars (prhs[0]); - plhs[0] = mxCreateNumericMatrix (m, n, mxCHAR_CLASS, - mxREAL); + plhs[0] = mxCreateNumericMatrix (m, n, mxCHAR_CLASS, mxREAL); po = mxGetChars (plhs[0]); for (j = 0; j < n; j++) for (i = 0; i < m; i++) - po [j*m + m - 1 - i] = pi [j*m + i]; + po[j*m + m - 1 - i] = pi[j*m + i]; }
--- a/examples/mystruct.c +++ b/examples/mystruct.c @@ -1,8 +1,8 @@ #include "mex.h" void -mexFunction (int nlhs, mxArray* plhs[], int nrhs, - const mxArray* prhs[]) +mexFunction (int nlhs, mxArray* plhs[], + int nrhs, const mxArray* prhs[]) { int i; mwIndex j; @@ -18,7 +18,7 @@ mexPrintf ("field %s(%d) = ", mxGetFieldNameByNumber (prhs[0], i), j); v = mxGetFieldByNumber (prhs[0], j, i); - mexCallMATLAB (0, 0, 1, &v, "disp"); + mexCallMATLAB (0, NULL, 1, &v, "disp"); } v = mxCreateStructMatrix (2, 2, 2, keys);
rename from examples/hello.cc rename to examples/oct_demo.cc --- a/examples/hello.cc +++ b/examples/oct_demo.cc @@ -1,4 +1,4 @@ -// hello.cc -- example of a dynamically linked function for Octave. +// oct_demo.cc -- example of a dynamically linked function for Octave. // To use this file, your version of Octave must support dynamic // linking. To find out if it does, type the command @@ -6,18 +6,17 @@ // octave_config_info ("ENABLE_DYNAMIC_LINKING") // // at the Octave prompt. Support for dynamic linking is included if -// this expression returns the string "true". +// this expression returns the string "yes". // // To compile this file, type the command // -// mkoctfile hello.cc +// mkoctfile oct_demo.cc // -// at the shell prompt. The script mkoctfile should have been -// installed along with Octave. Running it will create a file called -// hello.oct that can be loaded by Octave. To test the hello.oct -// file, start Octave and type the command +// from within Octave or from the shell prompt. This will create a file +// called oct_demo.oct that can be loaded by Octave. To test the +// oct_demo.oct file, start Octave and type the command // -// hello ("easy as", 1, 2, 3) +// oct_demo ("easy as", 1, 2, 3) // // at the Octave prompt. Octave should respond by printing // @@ -28,47 +27,34 @@ // 3 // ans = 3 -// Additional examples are available in the files in the src directory -// of the Octave distribution that use the macro DEFUN_DLD_BUILTIN. -// Currently, this includes the files -// -// balance.cc fft.cc ifft.cc minmax.cc sort.cc -// chol.cc fft2.cc ifft2.cc pinv.cc svd.cc -// colloc.cc filter.cc inv.cc qr.cc syl.cc -// dassl.cc find.cc log.cc quad.cc -// det.cc fsolve.cc lsode.cc qzval.cc -// eig.cc givens.cc lu.cc rand.cc -// expm.cc hess.cc minmax.cc schur.cc -// -// The difference between DEFUN_DLD and DEFUN_DLD_BUILTIN is that -// DEFUN_DLD_BUILTIN can define a built-in function that is not -// dynamically loaded if the operating system does not support dynamic -// linking. To define your own dynamically linked functions you -// should use DEFUN_DLD. - -#include <octave/config.h> +// Additional samples of real dynamically loaded functions are available in +// the files of the libinterp/dldfcn directory of the Octave distribution. +// See also the chapter External Code Interface in the documentation. #include <iostream> -#include <octave/defun-dld.h> -#include <octave/error.h> -#include <octave/oct-obj.h> -#include <octave/pager.h> -#include <octave/symtab.h> -#include <octave/variables.h> +#include <octave/oct.h> -// DEFUN_DLD and the macros that it depends on are defined in the -// files defun-dld.h, defun.h, and defun-int.h. +// Every user function should include <octave/oct.h> which imports the +// basic set of Octave header files required. In particular this will define +// the DEFUN_DLD macro (defun-dld.h) which is used for every user function +// that is visible to Octave. -// Note that the third parameter (nargout) is not used, so it is -// omitted from the list of arguments to DEFUN_DLD in order to avoid -// the warning from gcc about an unused function parameter. +// The four arguments to the DEFUN_DLD macro are: +// 1) The function name as seen in Octave. +// 2) The variable to hold any inputs (of type octave_value_list) +// 3) The number of output arguments +// 4) A string to use as help text if 'help <function_name>' is entered. +// +// Note below that the third parameter (nargout) of DEFUN_DLD is not used, +// so it is omitted from the list of arguments in order to avoid a warning +// from gcc about an unused function parameter. -DEFUN_DLD (hello, args, , - "[...] = hello (...)\n\ +DEFUN_DLD (oct_demo, args, , + "[...] = oct_demo (...)\n\ \n\ -Print greeting followed by the values of all the arguments passed.\n\ -Returns all arguments in reverse order.") +Print a greeting followed by the values of all the arguments passed.\n\ +Return all arguments in reverse order.") { // The list of values to return. See the declaration in oct-obj.h @@ -78,14 +64,14 @@ octave_stdout << "Hello, world!\n"; - // The arguments to this function are available in args. + // The inputs to this function are available in args. int nargin = args.length (); - // The octave_value_list class is a zero-based array of octave_value - // objects. The declaration for the octave_value class is in the - // file ov.h. The print() method will send its output to - // octave_stdout, so it will also end up going through the pager. + // The octave_value_list class is a zero-based array of octave_value objects. + // The declaration for the octave_value class is in the file ov.h. + // The print() method will send its output to octave_stdout, + // so it will also end up going through the pager. for (int i = 0; i < nargin; i++) {
--- a/examples/paramdemo.cc +++ b/examples/paramdemo.cc @@ -1,15 +1,14 @@ #include <octave/oct.h> -DEFUN_DLD (paramdemo, args, nargout, - "Parameter Check Demo.") +DEFUN_DLD (paramdemo, args, nargout, "Parameter Check Demo") { + octave_value retval; int nargin = args.length (); - octave_value retval; if (nargin != 1) print_usage (); else if (nargout != 0) - error ("paramdemo: function has no output arguments"); + error ("paramdemo: OUTPUT argument required"); else { NDArray m = args(0).array_value (); @@ -21,14 +20,11 @@ if (m.any_element_is_inf_or_nan ()) octave_stdout << " includes Inf or NaN values\n"; if (m.any_element_not_one_or_zero ()) - octave_stdout << - " includes other values than 1 and 0\n"; + octave_stdout << " includes other values than 1 and 0\n"; if (m.all_elements_are_int_or_inf_or_nan ()) - octave_stdout << - " includes only int, Inf or NaN values\n"; + octave_stdout << " includes only int, Inf or NaN values\n"; if (m.all_integers (min_val, max_val)) - octave_stdout << - " includes only integers in [-10,10]\n"; + octave_stdout << " includes only integers in [-10,10]\n"; } return retval; }
--- a/examples/standalone.cc +++ b/examples/standalone.cc @@ -5,15 +5,15 @@ main (void) { std::cout << "Hello Octave world!\n"; + int n = 2; Matrix a_matrix = Matrix (n, n); + for (octave_idx_type i = 0; i < n; i++) - { - for (octave_idx_type j = 0; j < n; j++) - { - a_matrix (i, j) = (i + 1) * 10 + (j + 1); - } - } + for (octave_idx_type j = 0; j < n; j++) + a_matrix(i,j) = (i + 1) * 10 + (j + 1); + std::cout << a_matrix; + return 0; }
--- a/examples/stringdemo.cc +++ b/examples/stringdemo.cc @@ -2,8 +2,8 @@ DEFUN_DLD (stringdemo, args, , "String Demo") { + octave_value_list retval; int nargin = args.length (); - octave_value_list retval; if (nargin != 1) print_usage (); @@ -13,20 +13,16 @@ if (! error_state) { - if (args(0).is_sq_string ()) - retval(1) = octave_value (ch, true); - else - retval(1) = octave_value (ch, true, '\''); + retval(1) = octave_value (ch, '\''); // Single Quote String octave_idx_type nr = ch.rows (); for (octave_idx_type i = 0; i < nr / 2; i++) { std::string tmp = ch.row_as_string (i); - ch.insert (ch.row_as_string (nr-i-1).c_str (), - i, 0); + ch.insert (ch.row_as_string (nr-i-1).c_str (), i, 0); ch.insert (tmp.c_str (), nr-i-1, 0); } - retval(0) = octave_value (ch, true); + retval(0) = octave_value (ch, '"'); // Double Quote String } } return retval;
--- a/examples/structdemo.cc +++ b/examples/structdemo.cc @@ -1,14 +1,15 @@ #include <octave/oct.h> #include <octave/ov-struct.h> -DEFUN_DLD (structdemo, args, , "Struct demo.") +DEFUN_DLD (structdemo, args, , "Struct Demo") { + octave_value retval; int nargin = args.length (); - octave_value retval; if (args.length () == 2) { octave_scalar_map arg0 = args(0).scalar_map_value (); + //octave_map arg0 = args(0).map_value (); if (! error_state) { @@ -17,6 +18,7 @@ if (! error_state) { octave_value tmp = arg0.contents (arg1); + //octave_value tmp = arg0.contents (arg1)(0); if (tmp.is_defined ()) { @@ -27,18 +29,17 @@ retval = octave_value (st); } else - error ("sruct does not contain field named '%s'\n", + error ("structdemo: struct does not have a field named '%s'\n", arg1.c_str ()); } else - error ("expecting character string as second argument"); + error ("structdemo: ARG2 must be a character string"); } else - error ("expecting struct as first argument"); + error ("structdemo: ARG1 must be a struct"); } else print_usage (); return retval; } -
--- a/examples/unwinddemo.cc +++ b/examples/unwinddemo.cc @@ -2,15 +2,16 @@ #include <octave/unwind-prot.h> void -err_hand (const char *fmt, ...) +my_err_handler (const char *fmt, ...) { // Do nothing!! } DEFUN_DLD (unwinddemo, args, nargout, "Unwind Demo") { + octave_value retval; int nargin = args.length (); - octave_value retval; + if (nargin < 2) print_usage (); else @@ -20,11 +21,13 @@ if (! error_state) { - unwind_protect::begin_frame ("Funwinddemo"); - unwind_protect_ptr (current_liboctave_warning_handler); - set_liboctave_warning_handler (err_hand); + // Declare unwind_protect frame which lasts as long as + // the variable frame has scope. + unwind_protect frame; + frame.protect_var (current_liboctave_warning_handler); + + set_liboctave_warning_handler (my_err_handler); retval = octave_value (quotient (a, b)); - unwind_protect::run_frame ("Funwinddemo"); } } return retval;