Mercurial > hg > octave-nkf
diff doc/interpreter/dynamic.txi @ 6571:24d9e0799603
[project @ 2007-04-25 03:20:17 by jwe]
author | jwe |
---|---|
date | Wed, 25 Apr 2007 03:20:17 +0000 |
parents | 81a8ab62b2b9 |
children | 8e7148b84b59 |
line wrap: on
line diff
--- a/doc/interpreter/dynamic.txi +++ b/doc/interpreter/dynamic.txi @@ -4,16 +4,16 @@ 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 has the option of directly calling C++ code +of Octave itself. Octave has the option of directly calling 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 +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. Before going further, you should first determine if you really need to -use dynamically linked functions at all. Before proceeding with writing +use dynamically linked functions at all. Before proceeding with writing any dynamically linked function to improve performance you should address ask yourself @@ -23,7 +23,7 @@ @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 +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 like matrix or zeros. @item @@ -37,7 +37,7 @@ Also, as oct- and mex-files are dynamically linked to octave, they introduce to possibility of having Octave abort due to coding errors in -the user code. For example a segmentation violation in the users code +the user code. For example a segmentation violation in the users code will cause Octave to abort. @menu @@ -87,7 +87,7 @@ "Hello World Help String") @{ int nargin = args.length (); - octave_stdout << "Hello World has " << nargin + octave_stdout << "Hello World has " << nargin << " input arguments and " << nargout << " output arguments.\n"; return octave_value_list (); @@ -96,16 +96,16 @@ @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 +function that can be dynamically linked to Octave. The easiest way to make available most of the definitions that might be necessary for an oct-file in Octave is to use the @code{#include <octave/oct.h>} -header. +header. The macro that defines the entry point into the dynamically loaded -function is DEFUN_DLD. This macro takes four arguments, these being +function is DEFUN_DLD. This macro takes four arguments, these being @enumerate 1 -@item The function name as it will be seen in Octave, +@item The function name as it will be seen in Octave, @item The list of arguments to the function of type octave_value_list, @item The number of output arguments, which can and often is omitted if not used, and @@ -113,14 +113,14 @@ @end enumerate The return type of functions defined with DEFUN_DLD is always -octave_value_list. +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 +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 +digit. Secondly, as Octave uses the function name to define the filename it attempts to find the function in, the function name in the DEFUN_DLD -macro must match the filename of the oct-file. Therefore, the above +macro must match the filename of the oct-file. Therefore, the above function should be in a file helloworld.cc, and it should be compiled to an oct-file using the command @@ -129,15 +129,15 @@ @end example This will create a file call helloworld.oct, that is the compiled -version of the function. It should be noted that it is perfectly +version of the function. It should be noted that it is perfectly acceptable to have more than one DEFUN_DLD function in a source -file. However, there must either be a symbolic link to the oct-file for +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 DEFUN_DLD macro or the 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 +function. After compiling this function as above, an example of its use is @example @@ -151,9 +151,9 @@ @subsection Matrices and Arrays in Oct-Files Octave supports a number of different array and matrix classes, the -majority of which are based on the Array class. The exception is the -sparse matrix types discussed separately below. There are three basic -matrix types +majority of which are based on the Array class. The exception is the +sparse matrix types discussed separately below. There are three basic +matrix types @table @asis @item Matrix @@ -164,7 +164,7 @@ A boolean matrix class defined in boolMatrix.h. @end table -These are the basic two-dimensional matrix types of octave. In +These are the basic two-dimensional matrix types of octave. In additional there are a number of multi-dimensional array types, these being @@ -183,11 +183,11 @@ @end table There are several basic means of constructing matrices of -multi-dimensional arrays. Considering the Matrix type as an example +multi-dimensional arrays. Considering the Matrix type as an example @itemize @bullet -@item -We can create an empty matrix or array with the empty constructor. For +@item +We can create an empty matrix or array with the empty constructor. For example @example @@ -195,8 +195,8 @@ @end example This can be used on all matrix and array types -@item -Define the dimensions of the matrix or array with a dim_vector. For +@item +Define the dimensions of the matrix or array with a dim_vector. For example @example @@ -209,7 +209,7 @@ This can be used on all matrix and array types @item -Define the number of rows and columns in the Matrix. For example +Define the number of rows and columns in the Matrix. For example @example Matrix a(2,2) @@ -225,9 +225,9 @@ @table @asis @item T& operator (octave_idx_type), T& elem(octave_idx_type) The () operator or elem method allow the values of the matrix or array -to be read or set. These can take a single argument, which is of type +to be read or set. These can take a single argument, which is of type octave_idx_type, that is the index into the matrix or -array. Additionally, the matrix type allows two argument versions of the +array. Additionally, the matrix type allows two argument versions of the () operator and elem method, giving the row and column index of the value to obtain or set. @@ -251,7 +251,7 @@ @end table Operators such an +, -, or * can be used on the majority of the above -types. In addition there are a number of methods that are of interest +types. In addition there are a number of methods that are of interest only for matrices such as transpose, hermitian, solve, etc. The typical way to extract a matrix or array from the input arguments of @@ -280,17 +280,17 @@ 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 NDArray and adds these together. Note that the array_value +accessing these arguments. It then obtains two multi-dimensional arrays +of type NDArray and adds these together. Note that the array_value method is called without using the is_matrix_type type, and instead the -error_state is checked before returning @code{A + B}. The reason to +error_state is checked before returning @code{A + B}. The reason to prefer this is that the arguments might be a type that is not an -NDArray, but it would make sense to convert it to one. The array_value +NDArray, but it would make sense to convert it to one. The array_value method allows this conversion to be performed transparently if possible, and sets error_state if it is not. @code{A + B}, operating on two NDArray's returns an NDArray, which is -cast to an octave_value on the return from the function. An example of +cast to an octave_value on the return from the function. An example of the use of this demonstration function is @example @@ -343,17 +343,17 @@ @end table All of these classes inherit from the @code{Sparse<T>} template class, -and so all have similar capabilities and usage. The @code{Sparse<T>} +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 with Octave's 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 similar with the existing Array classes. However, there are a +to their similar with the existing 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 possible to +will be described. Firstly, 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 +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. @@ -368,7 +368,7 @@ @subsubsection The Differences between the Array and Sparse Classes The number of elements in a sparse matrix is considered to be the number -of non-zero elements rather than the product of the dimensions. Therefore +of non-zero elements rather than the product of the dimensions. Therefore @example SparseMatrix sm; @@ -376,23 +376,23 @@ int nel = sm.nelem (); @end example -returns the number of non-zero elements. If the user really requires the +returns the number of non-zero elements. If the user really requires the number of elements in the matrix, including the non-zero elements, they -should use @code{numel} rather than @code{nelem}. Note that for very +should use @code{numel} rather than @code{nelem}. Note that for very large matrices, where the product of the two dimensions is large that the representation of the an unsigned int, then @code{numel} can overflow. An example is @code{speye(1e6)} which will create a matrix with a million -rows and columns, but only a million non-zero elements. Therefore the +rows and columns, but only a million non-zero elements. Therefore the number of rows by the number of columns in this case is more than two hundred times the maximum value that can be represented by an unsigned int. The use of @code{numel} should therefore be avoided useless it is known it won't overflow. Extreme care must be take with the elem method and the "()" operator, -which perform basically the same function. The reason is that if a +which perform basically the same function. The reason is that if a sparse object is non-const, then Octave will assume that a -request for a zero element in a sparse matrix is in fact a request -to create this element so it can be filled. Therefore a piece of +request for a zero element in a sparse matrix is in fact a request +to create this element so it can be filled. Therefore a piece of code like @example @@ -400,7 +400,7 @@ @dots{} for (int j = 0; j < nc; j++) for (int i = 0; i < nr; i++) - std::cerr << " (" << i << "," << j << "): " << sm(i,j) + std::cerr << " (" << i << "," << j << "): " << sm(i,j) << std::endl; @end example @@ -409,10 +409,10 @@ zero element in the matrix. An easy way of preventing the above from happening is to create a temporary -constant version of the sparse matrix. Note that only the container for +constant version of the sparse matrix. Note that only the container for the sparse matrix will be copied, while the actual representation of the -data will be shared between the two versions of the sparse matrix. So this -is not a costly operation. For example, the above would become +data will be shared between the two versions of the sparse matrix. So this +is not a costly operation. For example, the above would become @example SparseMatrix sm; @@ -420,17 +420,17 @@ 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::cerr << " (" << i << "," << j << "): " << tmp(i,j) << std::endl; @end example Finally, as the sparse types aren't just represented as a contiguous block of memory, the @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 +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. @@ -441,7 +441,7 @@ They 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, they can create a sparse matrix with the appropriate -amount of space and then fill in the values. Both techniques have their +amount of space and then fill in the values. Both techniques have their advantages and disadvantages. An example of how to create a small sparse matrix with the first technique @@ -460,67 +460,67 @@ SparseMatrix sm (data, ridx, cidx, nr, nc); @end example -which creates the matrix given in section @ref{Storage}. Note that +which creates the matrix given in section @ref{Storage}. Note that the compressed matrix format is not used at the time of the creation -of the matrix itself, however it is used internally. +of the matrix itself, however it 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 +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. 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 +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 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 +number of non-zero elements and then later fill those elements in. The +easiest way to do this is -@example +@example int nz = 4, nr = 3, nc = 4; SparseMatrix sm (nr, nc, nz); sm(0,0) = 1; sm(0,1) = 2; sm(1,3) = 3; sm(2,3) = 4; @end example -That creates the same matrix as previously. Again, although it is not +That creates the same matrix as previously. Again, although it is 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 +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. +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 not illegal to create a sparse matrix -with fewer elements than are actually inserted in the matrix. Therefore +a sparse matrix. Firstly, it is not illegal to create a sparse matrix +with fewer elements than are actually inserted in the matrix. Therefore -@example +@example int nz = 4, nr = 3, nc = 4; SparseMatrix sm (nr, nc, 0); sm(0,0) = 1; sm(0,1) = 2; sm(1,3) = 3; sm(2,3) = 4; @end example -is perfectly legal. However it is a very bad idea. The reason is that +is perfectly legal. 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 +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 not illegal to create a sparse matrix with +matrix. Furthermore, it is not illegal to create a sparse matrix with too much storage, so having @var{nz} above equaling 6 is also legal. The disadvantage is that the matrix occupies more memory than strictly needed. It is not always easy to known the number of non-zero elements prior -to filling a matrix. For this reason the additional storage for the +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 +@dfn{maybe_compress} function. Furthermore, the maybe_compress can deallocate the unused storage, but it can equally 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 '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 +to be '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 @example @@ -530,7 +530,7 @@ 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; + 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 example @@ -539,19 +539,19 @@ possible, as it will slow the creation of the matrices. 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 +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 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 no nz SparseMatrix sm (nr, nc, nz); Matrix m = arg.matrix_value (); @@ -577,16 +577,16 @@ which is probably the most efficient means of creating the sparse matrix. Finally, it might sometimes arise that the amount of storage initially -created is insufficient to completely store the sparse matrix. Therefore, +created is insufficient to completely store the sparse matrix. Therefore, the method @code{change_capacity} exists to reallocate the sparse memory. -The above example would then be modified as +The above example would then be modified as @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 no nz SparseMatrix sm (nr, nc, nz); Matrix m = arg.matrix_value (); @@ -615,9 +615,9 @@ @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 +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 +at the same time, additional memory is needed. Therefore if possible this should be avoided. @node OctUse @@ -649,7 +649,7 @@ @node Using Strings in Oct-Files @subsection Using Strings in Oct-Files -In Octave a string is just a special Array class. Consider the example +In Octave a string is just a special Array class. Consider the example @example @group @@ -658,7 +658,7 @@ DEFUN_DLD (stringdemo, args, , "String Demo") @{ int nargin = args.length(); - octave_value_list retval; + octave_value_list retval; if (nargin != 1) print_usage (); @@ -695,9 +695,9 @@ s0 = ["First String";"Second String"]; [s1,s2] = stringdemo (s0) @result{}s1 = Second String - First String + First String -@result{}s2 = First String +@result{}s2 = First String Second String typeinfo (s2) @@ -708,7 +708,7 @@ @end example One additional complication of strings in Octave is the difference -between single quoted and double quoted strings. To find out if an +between single quoted and double quoted strings. To find out if an octave_value contains a single or double quoted string an example is @example @@ -722,7 +722,7 @@ Note however, that both types of strings are represented by the charNDArray type, and so when assigning to an octave_value, the type of -string should be specified. For example +string should be specified. For example @example @group @@ -737,9 +737,9 @@ @node Cell Arrays in Oct-Files @subsection Cell Arrays in Oct-Files -Octave's cell type is equally accessible within an oct-files. A cell +Octave's cell type is equally accessible within an oct-files. A cell array is just an array of octave_values, and so each element of the cell -array can then be treated just like any other octave_value. A simple +array can then be treated just like any other octave_value. A simple example is @example @@ -747,7 +747,7 @@ #include <octave/oct.h> #include <octave/Cell.h> -DEFUN_DLD (celldemo, args, , "Cell Demo") +DEFUN_DLD (celldemo, args, , "Cell Demo") @{ octave_value_list retval; int nargin = args.length(); @@ -767,9 +767,9 @@ @end example Note that cell arrays are used less often in standard oct-files and so -the Cell.h header file must be explicitly included. The rest of this +the Cell.h header file must be explicitly included. The rest of this example extracts the octave_values one by one from the cell array and -returns be as individual return arguments. For example consider +returns be as individual return arguments. For example consider @example @group @@ -788,7 +788,7 @@ @subsection Using Structures in Oct-Files A structure in Octave is map between a number of fields represented and -their values. The "Standard Template Library" map class is used, with +their values. The "Standard Template Library" map class is used, with the pair consisting of a std::string and an octave Cell variable. A simple example demonstrating the use of structures within oct-files is @@ -814,7 +814,7 @@ @{ // The following two lines might be written as // octave_value tmp; - // for (Octave_map::iterator p0 = arg0.begin() ; + // for (Octave_map::iterator p0 = arg0.begin() ; // p0 != arg0.end(); p0++ ) // if (arg0.key (p0) == arg1) // @{ @@ -829,7 +829,7 @@ retval = octave_value (st); @} @} - return retval; + return retval; @} @end group @end example @@ -850,24 +850,24 @@ As can be seen the @code{contents} method of the @code{Octave_map} class returns a Cell which allows Structure Arrays to be -represented. Therefore, to obtain the underlying octave_value we write +represented. Therefore, to obtain the underlying octave_value we write @example octave_value tmp = arg0.contents (p1) (0); @end example -where the trailing (0) is the () operator on the Cell array. +where the trailing (0) is the () operator on the Cell array. @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 +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 +@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 +that no global variable of the desired name is found. An example of the use of these two functions is @example @@ -898,7 +898,7 @@ return retval; @} @end group -@end example +@end example An example of its use is @@ -920,12 +920,12 @@ 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 +itself. For example the @code{quad} function is an oct-file that calculates the definite integral by quadrature over a user supplied function. -There are also many ways in which a function might be passed. It might -be passed as one of +There are also many ways in which a function might be passed. It might +be passed as one of @enumerate 1 @item Function Handle @@ -935,7 +935,7 @@ @end enumerate The example below demonstrates an example that accepts all four means of -passing a function to an oct-file. +passing a function to an oct-file. @example @group @@ -954,7 +954,7 @@ 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 () || + if (args(0).is_function_handle () || args(0).is_inline_function ()) @{ octave_function *fcn = args(0).function_value (); @@ -994,8 +994,8 @@ @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 -user supplied function as an octave_function. In that case the string +function is different. In some cases it is necessary to always have the +user supplied function as an octave_function. In that case the string argument can be used to create a temporary function like @example @@ -1004,7 +1004,7 @@ std::string fname = "function y = "; fname.append (fcn_name); fname.append ("(x) y = "); - fcn = extract_function (args(0), "funcdemo", fcn_name, + fcn = extract_function (args(0), "funcdemo", fcn_name, fname, "; endfunction"); @dots{} if (fcn_name.length()) @@ -1012,7 +1012,7 @@ @end group @end example -There are two important things to know in this case. The number of input +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. @@ -1021,9 +1021,9 @@ @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 +functions can easily be called directly from C++. One possible issue is the declarations of the external C functions might need to be explicitly -defined as C functions to the compiler. If the declarations of the +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 @@ -1031,7 +1031,7 @@ @example @group #ifdef __cplusplus -extern "C" +extern "C" @{ #endif #include "foo.h" @@ -1041,27 +1041,27 @@ @end group @end example -Calling Fortran code however can pose some difficulties. This is due to +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 +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 +replace the Fortran @code{STOP} function. @code{XSTOPX} uses the Octave exception handler to treat failing cases in the fortran code -explicitly. Note that Octave supplies its own replacement blas +explicitly. Note that Octave supplies its own replacement blas @code{XERBLA} function, which uses @code{XSTOPX}. If the underlying code calls @code{XSTOP}, then the @code{F77_XFCN} -macro should be used to call the underlying fortran function. The Fortran +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{XSTOP} will not be called, +@code{f77_exception_encountered}. If @code{XSTOP} will not be called, then the @code{F77_FCN} macro should be used instead to call the Fortran code. There is no harm in using @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 @code{F77_FCN} +there is potentially an overhead in doing so. However, if @code{F77_FCN} is used with code that calls @code{XSTOP}, Octave can generate a segmentation fault. @@ -1073,17 +1073,17 @@ #include <octave/oct.h> #include <octave/f77-fcn.h> -extern "C" +extern "C" @{ - F77_RET_T - F77_FUNC (fortsub, FORTSUB) - (const int&, double*, F77_CHAR_ARG_DECL + F77_RET_T + F77_FUNC (fortsub, FORTSUB) + (const int&, double*, F77_CHAR_ARG_DECL F77_CHAR_ARG_LEN_DECL); @} DEFUN_DLD (fortdemo , args , , "Fortran Demo.") @{ - octave_value_list retval; + octave_value_list retval; int nargin = args.length(); if (nargin != 1) print_usage (); @@ -1140,7 +1140,7 @@ 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. An example of the behavior of this function is @example @group @@ -1159,9 +1159,9 @@ @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 -taken to avoid memory leaks. The preferred manner in which to allocate -memory for use locally is to use the OCTAVE_LOCAL_BUFFER macro. An +new/delete operators can be used. However, in that case care must be +taken to avoid memory leaks. The preferred manner in which to allocate +memory for use locally is to use the OCTAVE_LOCAL_BUFFER macro. An example of its use is @example @@ -1180,11 +1180,11 @@ @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 @kbd{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 +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}, -the @code{OCTAVE_QUIT} macro is supplied. For example +the @code{OCTAVE_QUIT} macro is supplied. For example @example @group @@ -1197,7 +1197,7 @@ @end example The presence of the OCTAVE_QUIT macro in the inner loop allows Octave to -treat the user request with the @kbd{Control-C}. Without this macro, the user +treat the user request with the @kbd{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. @@ -1207,8 +1207,8 @@ When creating an oct-file that uses an external libraries, the function might spend a significant portion of its time in the external -library. It is not generally possible to use the OCTAVE_QUIT macro in -this case. The alternative in this case is +library. It is not generally possible to use the OCTAVE_QUIT macro in +this case. The alternative in this case is @example @group @@ -1220,14 +1220,14 @@ The disadvantage of this is that if the foreign code allocates any memory internally, then this memory might be lost during an interrupt, -without being deallocated. Therefore, ideally Octave itself should +without being deallocated. Therefore, ideally Octave itself should allocate any memory that is needed by the foreign code, with either the fortran_vec method or the OCTAVE_LOCAL_BUFFER macro. -The Octave unwind_protect mechanism (@ref{The unwind_protect Statement}) -can also be used in oct-files. In conjunction with the exception +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 @@ -1297,14 +1297,14 @@ @cindex mex 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 non Octave users. However, as mex-files expose the +and used with Octave. This interface can also be used to share code +between Octave and non Octave users. However, as mex-files expose the intern API of a product alternative to Octave, and the internal structure of Octave is different to this product, a mex-file can never -have the same performance in Octave as the equivalent oct-file. In +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 +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. @@ -1319,8 +1319,8 @@ @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 the -commandline. However, to avoid issues with the installation of other +@code{mex}. The first can either be used from within Octave or from the +commandline. However, to avoid issues with the installation of other products, the use of the command @code{mex} is limited to within Octave. @DOCSTRING(mex) @@ -1329,7 +1329,7 @@ One important difference between the use of mex with other products and with 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 +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 @@ -1373,7 +1373,7 @@ @section Standalone Programs The libraries Octave itself uses, can be utilized in standalone -applications. These applications then have access, for example, to the +applications. These applications then have access, for example, to the array and matrix classes as well as to all the Octave algorithms. The following C++ program, uses class Matrix from liboctave.a or liboctave.so.