Mercurial > octave-libgccjit
annotate doc/interpreter/dynamic.txi @ 14138:72c96de7a403 stable
maint: update copyright notices for 2012
| author | John W. Eaton <jwe@octave.org> |
|---|---|
| date | Mon, 02 Jan 2012 14:25:41 -0500 |
| parents | d0b799dafede |
| children | 460a3c6d8bf1 ddc651eecf7a |
| rev | line source |
|---|---|
|
14138
72c96de7a403
maint: update copyright notices for 2012
John W. Eaton <jwe@octave.org>
parents:
12575
diff
changeset
|
1 @c Copyright (C) 2007-2012 John W. Eaton and David Bateman |
| 7018 | 2 @c Copyright (C) 2007 Paul Thomas and Christoph Spiel |
| 3 @c | |
| 4 @c This file is part of Octave. | |
| 5 @c | |
| 6 @c Octave is free software; you can redistribute it and/or modify it | |
| 7 @c under the terms of the GNU General Public License as published by the | |
| 8 @c Free Software Foundation; either version 3 of the License, or (at | |
| 9 @c your option) any later version. | |
| 10 @c | |
| 11 @c Octave is distributed in the hope that it will be useful, but WITHOUT | |
| 12 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
| 13 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
| 14 @c for more details. | |
| 15 @c | |
| 16 @c You should have received a copy of the GNU General Public License | |
| 17 @c along with Octave; see the file COPYING. If not, see | |
| 18 @c <http://www.gnu.org/licenses/>. | |
| 6578 | 19 |
| 6569 | 20 @node Dynamically Linked Functions |
| 21 @appendix Dynamically Linked Functions | |
| 22 @cindex dynamic-linking | |
| 23 | |
| 24 Octave has the possibility of including compiled code as dynamically | |
| 25 linked extensions and then using these extensions as if they were part | |
| 8828 | 26 of Octave itself. Octave can call C++ code |
| 6569 | 27 through its native oct-file interface or C code through its mex |
| 6571 | 28 interface. It can also indirectly call functions written in any other |
| 29 language through a simple wrapper. The reasons to write code in a | |
| 6569 | 30 compiled language might be either to link to an existing piece of code |
| 31 and allow it to be used within Octave, or to allow improved performance | |
| 32 for key pieces of code. | |
| 33 | |
| 34 Before going further, you should first determine if you really need to | |
| 6571 | 35 use dynamically linked functions at all. Before proceeding with writing |
| 6569 | 36 any dynamically linked function to improve performance you should |
| 37 address ask yourself | |
| 38 | |
| 39 @itemize @bullet | |
| 40 @item | |
| 6939 | 41 Can I get the same functionality using the Octave scripting language only? |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
42 |
| 6569 | 43 @item |
| 6572 | 44 Is it thoroughly optimized Octave code? Vectorization of Octave code, |
| 6569 | 45 doesn't just make it concise, it generally significantly improves its |
| 6571 | 46 performance. Above all, if loops must be used, make sure that the |
| 6569 | 47 allocation of space for variables takes place outside the loops using an |
| 8828 | 48 assignment to a matrix of the right size, or zeros. |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
49 |
| 6569 | 50 @item |
| 51 Does it make as much use as possible of existing built-in library | |
| 6572 | 52 routines? These are highly optimized and many do not carry the overhead |
| 6569 | 53 of being interpreted. |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
54 |
| 6569 | 55 @item |
| 56 Does writing a dynamically linked function represent useful investment | |
| 57 of your time, relative to staying in Octave? | |
| 58 @end itemize | |
| 59 | |
| 8475 | 60 Also, as oct- and mex-files are dynamically linked to Octave, they |
|
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
8097
diff
changeset
|
61 introduce the possibility of Octave crashing due to errors in |
| 7001 | 62 the user code. For example a segmentation violation in the user's code |
| 6569 | 63 will cause Octave to abort. |
| 64 | |
| 65 @menu | |
| 6572 | 66 * Oct-Files:: |
| 67 * Mex-Files:: | |
| 68 * Standalone Programs:: | |
| 6569 | 69 @end menu |
| 70 | |
| 71 @node Oct-Files | |
| 72 @section Oct-Files | |
| 73 @cindex oct-files | |
| 74 @cindex mkoctfile | |
| 75 @cindex oct | |
| 76 | |
| 77 @menu | |
| 6572 | 78 * Getting Started with Oct-Files:: |
| 79 * Matrices and Arrays in Oct-Files:: | |
| 80 * Character Strings in Oct-Files:: | |
| 81 * Cell Arrays in Oct-Files:: | |
| 82 * Structures in Oct-Files:: | |
| 83 * Sparse Matrices in Oct-Files:: | |
| 84 * Accessing Global Variables in Oct-Files:: | |
| 85 * Calling Octave Functions from Oct-Files:: | |
| 86 * Calling External Code from Oct-Files:: | |
| 87 * Allocating Local Memory in Oct-Files:: | |
| 88 * Input Parameter Checking in Oct-Files:: | |
| 89 * Exception and Error Handling in Oct-Files:: | |
| 90 * Documentation and Test of Oct-Files:: | |
| 6593 | 91 @c * Application Programming Interface for Oct-Files:: |
| 6569 | 92 @end menu |
| 93 | |
| 94 @node Getting Started with Oct-Files | |
| 95 @subsection Getting Started with Oct-Files | |
| 96 | |
| 97 The basic command to build oct-files is @code{mkoctfile} and it can be | |
| 98 call from within octave or from the command line. | |
| 99 | |
| 100 @DOCSTRING(mkoctfile) | |
| 101 | |
|
12489
ac3bdc27734e
Clarify in manual that the mkoctfile examples are in C++
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
11573
diff
changeset
|
102 Consider the short C++ example: |
| 6569 | 103 |
| 9906 | 104 @example |
| 105 @group | |
| 106 @EXAMPLEFILE(helloworld.cc) | |
| 107 @end group | |
| 108 @end example | |
| 6569 | 109 |
| 110 This example although short introduces the basics of writing a C++ | |
|
12575
d0b799dafede
Grammarcheck files for 3.4.1 release.
Rik <octave@nomad.inbox5.com>
parents:
12489
diff
changeset
|
111 function that can be dynamically linked to Octave. The easiest way to |
|
12489
ac3bdc27734e
Clarify in manual that the mkoctfile examples are in C++
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
11573
diff
changeset
|
112 make available most of the definitions that might be necessary for a C++ |
|
ac3bdc27734e
Clarify in manual that the mkoctfile examples are in C++
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
11573
diff
changeset
|
113 oct-file in Octave is to use the @code{#include <octave/oct.h>} header. |
|
ac3bdc27734e
Clarify in manual that the mkoctfile examples are in C++
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
11573
diff
changeset
|
114 Note that @file{octave/oct.h} is a C++ header and cannot be directly |
|
12575
d0b799dafede
Grammarcheck files for 3.4.1 release.
Rik <octave@nomad.inbox5.com>
parents:
12489
diff
changeset
|
115 @code{#include}'ed in a C source file, nor any other language. What |
|
12489
ac3bdc27734e
Clarify in manual that the mkoctfile examples are in C++
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
11573
diff
changeset
|
116 follows is mostly C++, with a discussion of other languages in section |
|
ac3bdc27734e
Clarify in manual that the mkoctfile examples are in C++
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
11573
diff
changeset
|
117 @ref{Calling External Code from Oct-Files}. |
| 6569 | 118 |
| 119 The macro that defines the entry point into the dynamically loaded | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
120 function is @w{@code{DEFUN_DLD}}. This macro takes four arguments, these being |
| 6569 | 121 |
| 122 @enumerate 1 | |
| 6571 | 123 @item The function name as it will be seen in Octave, |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
124 |
| 6572 | 125 @item The list of arguments to the function of type @code{octave_value_list}, |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
126 |
| 6569 | 127 @item The number of output arguments, which can and often is omitted if |
| 128 not used, and | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
129 |
| 6569 | 130 @item The string that will be seen as the help text of the function. |
| 131 @end enumerate | |
| 132 | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
133 The return type of functions defined with @w{@code{DEFUN_DLD}} is always |
| 6572 | 134 @code{octave_value_list}. |
| 6569 | 135 |
| 136 There are a couple of important considerations in the choice of function | |
| 6571 | 137 name. Firstly, it must be a valid Octave function name and so must be a |
| 6569 | 138 sequence of letters, digits and underscores, not starting with a |
| 6571 | 139 digit. Secondly, as Octave uses the function name to define the filename |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
140 it attempts to find the function in, the function name in the |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
141 @w{@code{DEFUN_DLD}} macro must match the filename of the oct-file. Therefore, |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
142 the above function should be in a file @file{helloworld.cc}, and it should be |
| 6572 | 143 compiled to an oct-file using the command |
| 6569 | 144 |
| 145 @example | |
| 146 mkoctfile helloworld.cc | |
| 147 @end example | |
| 148 | |
| 8828 | 149 This will create a file called @file{helloworld.oct}, that is the compiled |
| 6571 | 150 version of the function. It should be noted that it is perfectly |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
151 acceptable to have more than one @w{@code{DEFUN_DLD}} function in a source |
| 6571 | 152 file. However, there must either be a symbolic link to the oct-file for |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
153 each of the functions defined in the source code with the @w{@code{DEFUN_DLD}} |
| 6569 | 154 macro or the autoload (@ref{Function Files}) function should be used. |
| 155 | |
| 156 The rest of this function then shows how to find the number of input | |
| 157 arguments, how to print through the octave pager, and return from the | |
| 6571 | 158 function. After compiling this function as above, an example of its use |
| 6569 | 159 is |
| 160 | |
| 161 @example | |
| 162 @group | |
| 6572 | 163 helloworld (1, 2, 3) |
| 164 @print{} Hello World has 3 input arguments and 0 output arguments. | |
| 6569 | 165 @end group |
| 166 @end example | |
| 167 | |
| 168 @node Matrices and Arrays in Oct-Files | |
| 169 @subsection Matrices and Arrays in Oct-Files | |
| 170 | |
| 171 Octave supports a number of different array and matrix classes, the | |
| 6571 | 172 majority of which are based on the Array class. The exception is the |
| 173 sparse matrix types discussed separately below. There are three basic | |
| 174 matrix types | |
| 6569 | 175 |
| 6572 | 176 @table @code |
| 6569 | 177 @item Matrix |
| 178 A double precision matrix class defined in dMatrix.h, | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
179 |
| 6569 | 180 @item ComplexMatrix |
| 181 A complex matrix class defined in CMatrix.h, and | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
182 |
| 6569 | 183 @item BoolMatrix |
| 184 A boolean matrix class defined in boolMatrix.h. | |
| 185 @end table | |
| 186 | |
| 6571 | 187 These are the basic two-dimensional matrix types of octave. In |
| 6569 | 188 additional there are a number of multi-dimensional array types, these |
| 189 being | |
| 190 | |
| 6572 | 191 @table @code |
| 6569 | 192 @item NDArray |
| 6572 | 193 A double precision array class defined in @file{dNDArray.h} |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
194 |
| 6569 | 195 @item ComplexNDarray |
| 6572 | 196 A complex array class defined in @file{CNDArray.h} |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
197 |
| 6569 | 198 @item boolNDArray |
| 6572 | 199 A boolean array class defined in @file{boolNDArray.h} |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
200 |
| 6572 | 201 @item int8NDArray |
| 202 @itemx int16NDArray | |
| 203 @itemx int32NDArray | |
| 204 @itemx int64NDArray | |
| 205 8, 16, 32 and 64-bit signed array classes defined in | |
| 206 @file{int8NDArray.h}, @file{int16NDArray.h}, etc. | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
207 |
| 6572 | 208 @item uint8NDArray |
| 209 @itemx uint16NDArray | |
| 210 @itemx uint32NDArray | |
| 211 @itemx uint64NDArray | |
| 212 8, 16, 32 and 64-bit unsigned array classes defined in | |
| 213 @file{uint8NDArray.h}, @file{uint16NDArray.h}, etc. | |
| 6569 | 214 @end table |
| 215 | |
| 216 There are several basic means of constructing matrices of | |
| 6572 | 217 multi-dimensional arrays. Considering the @code{Matrix} type as an |
| 218 example | |
| 6569 | 219 |
| 220 @itemize @bullet | |
| 6571 | 221 @item |
| 222 We can create an empty matrix or array with the empty constructor. For | |
| 6569 | 223 example |
| 224 | |
| 225 @example | |
| 226 Matrix a; | |
| 227 @end example | |
| 228 | |
| 229 This can be used on all matrix and array types | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
230 |
| 6571 | 231 @item |
| 232 Define the dimensions of the matrix or array with a dim_vector. For | |
| 6569 | 233 example |
| 234 | |
| 235 @example | |
| 236 @group | |
| 6572 | 237 dim_vector dv (2); |
| 6569 | 238 dv(0) = 2; dv(1) = 2; |
| 6572 | 239 Matrix a (dv); |
| 6569 | 240 @end group |
| 241 @end example | |
| 242 | |
| 243 This can be used on all matrix and array types | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
244 |
| 6569 | 245 @item |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
246 Define the number of rows and columns in the matrix. For example: |
| 6569 | 247 |
| 248 @example | |
| 6572 | 249 Matrix a (2, 2) |
| 6569 | 250 @end example |
| 251 | |
| 252 However, this constructor can only be used with the matrix types. | |
| 253 @end itemize | |
| 254 | |
| 255 These types all share a number of basic methods and operators, a | |
| 256 selection of which include | |
| 257 | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
258 @deftypefn Method T& {operator ()} (octave_idx_type) |
| 6572 | 259 @deftypefnx Method T& elem (octave_idx_type) |
| 260 The @code{()} operator or @code{elem} method allow the values of the | |
| 261 matrix or array to be read or set. These can take a single argument, | |
| 262 which is of type @code{octave_idx_type}, that is the index into the matrix or | |
| 6571 | 263 array. Additionally, the matrix type allows two argument versions of the |
| 6572 | 264 @code{()} operator and elem method, giving the row and column index of the |
| 6569 | 265 value to obtain or set. |
| 6572 | 266 @end deftypefn |
| 6569 | 267 |
| 7001 | 268 Note that these functions do significant error checking and so in some |
| 269 circumstances the user might prefer to access the data of the array or | |
|
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
9906
diff
changeset
|
270 matrix directly through the @nospell{fortran_vec} method discussed below. |
| 6572 | 271 |
| 272 @deftypefn Method octave_idx_type nelem (void) const | |
| 6569 | 273 The total number of elements in the matrix or array. |
| 6572 | 274 @end deftypefn |
| 275 | |
| 276 @deftypefn Method size_t byte_size (void) const | |
| 6569 | 277 The number of bytes used to store the matrix or array. |
| 6572 | 278 @end deftypefn |
| 279 | |
| 280 @deftypefn Method dim_vector dims (void) const | |
| 6569 | 281 The dimensions of the matrix or array in value of type dim_vector. |
| 6572 | 282 @end deftypefn |
| 283 | |
| 284 @deftypefn Method void resize (const dim_vector&) | |
| 285 A method taking either an argument of type @code{dim_vector}, or in the | |
| 286 case of a matrix two arguments of type @code{octave_idx_type} defining | |
| 287 the number of rows and columns in the matrix. | |
| 288 @end deftypefn | |
| 289 | |
| 290 @deftypefn Method T* fortran_vec (void) | |
| 6569 | 291 This method returns a pointer to the underlying data of the matrix or a |
| 292 array so that it can be manipulated directly, either within Octave or by | |
| 293 an external library. | |
| 6572 | 294 @end deftypefn |
| 6569 | 295 |
| 6572 | 296 Operators such an @code{+}, @code{-}, or @code{*} can be used on the |
| 297 majority of the above types. In addition there are a number of methods | |
| 298 that are of interest only for matrices such as @code{transpose}, | |
| 299 @code{hermitian}, @code{solve}, etc. | |
| 6569 | 300 |
| 301 The typical way to extract a matrix or array from the input arguments of | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
302 @w{@code{DEFUN_DLD}} function is as follows |
| 6569 | 303 |
| 9906 | 304 @example |
| 305 @group | |
| 306 @EXAMPLEFILE(addtwomatrices.cc) | |
| 307 @end group | |
| 308 @end example | |
| 6569 | 309 |
| 310 To avoid segmentation faults causing Octave to abort, this function | |
| 311 explicitly checks that there are sufficient arguments available before | |
| 6571 | 312 accessing these arguments. It then obtains two multi-dimensional arrays |
| 6572 | 313 of type @code{NDArray} and adds these together. Note that the array_value |
| 314 method is called without using the @code{is_matrix_type} type, and instead the | |
| 6571 | 315 error_state is checked before returning @code{A + B}. The reason to |
| 6569 | 316 prefer this is that the arguments might be a type that is not an |
| 6572 | 317 @code{NDArray}, but it would make sense to convert it to one. The |
| 318 @code{array_value} method allows this conversion to be performed | |
| 319 transparently if possible, and sets @code{error_state} if it is not. | |
| 6569 | 320 |
| 6572 | 321 @code{A + B}, operating on two @code{NDArray}'s returns an |
| 322 @code{NDArray}, which is cast to an @code{octave_value} on the return | |
| 323 from the function. An example of the use of this demonstration function | |
| 324 is | |
| 6569 | 325 |
| 326 @example | |
| 327 @group | |
| 6572 | 328 addtwomatrices (ones (2, 2), ones (2, 2)) |
| 6569 | 329 @result{} 2 2 |
| 330 2 2 | |
| 331 @end group | |
| 332 @end example | |
| 333 | |
| 6572 | 334 A list of the basic @code{Matrix} and @code{Array} types, the methods to |
| 335 extract these from an @code{octave_value} and the associated header is | |
| 336 listed below. | |
| 6569 | 337 |
| 338 @multitable @columnfractions .3 .4 .3 | |
| 6572 | 339 @item @code{RowVector} @tab @code{row_vector_value} @tab @file{dRowVector.h} |
| 340 @item @code{ComplexRowVector} @tab @code{complex_row_vector_value} @tab @file{CRowVector.h} | |
| 341 @item @code{ColumnVector} @tab @code{column_vector_value} @tab @file{dColVector.h} | |
| 342 @item @code{ComplexColumnVector} @tab @code{complex_column_vector_value} @tab @file{CColVector.h} | |
| 343 @item @code{Matrix} @tab @code{matrix_value} @tab @file{dMatrix.h} | |
| 344 @item @code{ComplexMatrix} @tab @code{complex_matrix_value} @tab @file{CMatrix.h} | |
| 345 @item @code{boolMatrix} @tab @code{bool_matrix_value} @tab @file{boolMatrix.h} | |
| 346 @item @code{charMatrix} @tab @code{char_matrix_value} @tab @file{chMatrix.h} | |
| 347 @item @code{NDArray} @tab @code{array_value} @tab @file{dNDArray.h} | |
| 348 @item @code{ComplexNDArray} @tab @code{complex_array_value} @tab @file{CNDArray.h} | |
| 349 @item @code{boolNDArray} @tab @code{bool_array_value} @tab @file{boolNDArray.h} | |
| 350 @item @code{charNDArray} @tab @code{char_array_value} @tab @file{charNDArray.h} | |
| 351 @item @code{int8NDArray} @tab @code{int8_array_value} @tab @file{int8NDArray.h} | |
| 352 @item @code{int16NDArray} @tab @code{int16_array_value} @tab @file{int16NDArray.h} | |
| 353 @item @code{int32NDArray} @tab @code{int32_array_value} @tab @file{int32NDArray.h} | |
| 354 @item @code{int64NDArray} @tab @code{int64_array_value} @tab @file{int64NDArray.h} | |
| 355 @item @code{uint8NDArray} @tab @code{uint8_array_value} @tab @file{uint8NDArray.h} | |
| 356 @item @code{uint16NDArray} @tab @code{uint16_array_value} @tab @file{uint16NDArray.h} | |
| 357 @item @code{uint32NDArray} @tab @code{uint32_array_value} @tab @file{uint32NDArray.h} | |
| 358 @item @code{uint64NDArray} @tab @code{uint64_array_value} @tab @file{uint64NDArray.h} | |
| 6569 | 359 @end multitable |
| 360 | |
| 6572 | 361 @node Character Strings in Oct-Files |
| 362 @subsection Character Strings in Oct-Files | |
| 363 | |
| 364 In Octave a character string is just a special @code{Array} class. | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
365 Consider the example: |
| 6572 | 366 |
| 9906 | 367 @example |
| 368 @EXAMPLEFILE(stringdemo.cc) | |
| 369 @end example | |
| 6572 | 370 |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
371 An example of the use of this function is |
| 6572 | 372 |
| 373 @example | |
| 374 @group | |
| 375 s0 = ["First String"; "Second String"]; | |
| 376 [s1,s2] = stringdemo (s0) | |
| 377 @result{} s1 = Second String | |
| 378 First String | |
| 379 | |
| 380 @result{} s2 = First String | |
| 381 Second String | |
| 382 | |
| 383 typeinfo (s2) | |
| 384 @result{} sq_string | |
| 385 typeinfo (s1) | |
| 386 @result{} string | |
| 387 @end group | |
| 388 @end example | |
| 389 | |
| 390 One additional complication of strings in Octave is the difference | |
| 391 between single quoted and double quoted strings. To find out if an | |
| 392 @code{octave_value} contains a single or double quoted string an example is | |
| 393 | |
| 394 @example | |
| 395 @group | |
| 396 if (args(0).is_sq_string ()) | |
| 7081 | 397 octave_stdout << |
| 398 "First argument is a singularly quoted string\n"; | |
| 6572 | 399 else if (args(0).is_dq_string ()) |
| 7081 | 400 octave_stdout << |
| 401 "First argument is a doubly quoted string\n"; | |
| 6572 | 402 @end group |
| 403 @end example | |
| 404 | |
| 405 Note however, that both types of strings are represented by the | |
| 406 @code{charNDArray} type, and so when assigning to an | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
407 @code{octave_value}, the type of string should be specified. For example: |
| 6572 | 408 |
| 409 @example | |
| 410 @group | |
| 411 octave_value_list retval; | |
| 412 charNDArray c; | |
| 413 @dots{} | |
| 6577 | 414 // Create single quoted string |
| 415 retval(1) = octave_value (ch, true, '\''); | |
| 416 | |
| 417 // Create a double quoted string | |
| 418 retval(0) = octave_value (ch, true); | |
| 6572 | 419 @end group |
| 420 @end example | |
| 421 | |
| 422 @node Cell Arrays in Oct-Files | |
| 423 @subsection Cell Arrays in Oct-Files | |
| 424 | |
| 7001 | 425 Octave's cell type is equally accessible within oct-files. A cell |
| 6572 | 426 array is just an array of @code{octave_value}s, and so each element of the cell |
| 427 array can then be treated just like any other @code{octave_value}. A simple | |
| 428 example is | |
| 429 | |
| 9906 | 430 @example |
| 431 @group | |
| 432 @EXAMPLEFILE(celldemo.cc) | |
| 433 @end group | |
| 434 @end example | |
| 6572 | 435 |
| 436 Note that cell arrays are used less often in standard oct-files and so | |
| 437 the @file{Cell.h} header file must be explicitly included. The rest of this | |
| 438 example extracts the @code{octave_value}s one by one from the cell array and | |
| 439 returns be as individual return arguments. For example consider | |
| 440 | |
| 441 @example | |
| 442 @group | |
| 443 [b1, b2, b3] = celldemo (@{1, [1, 2], "test"@}) | |
| 444 @result{} | |
| 445 b1 = 1 | |
| 446 b2 = | |
| 447 | |
| 448 1 2 | |
| 449 | |
| 450 b3 = test | |
| 451 @end group | |
| 452 @end example | |
| 453 | |
| 454 @node Structures in Oct-Files | |
| 455 @subsection Structures in Oct-Files | |
| 456 | |
| 457 A structure in Octave is map between a number of fields represented and | |
| 458 their values. The Standard Template Library @code{map} class is used, | |
| 459 with the pair consisting of a @code{std::string} and an octave | |
| 460 @code{Cell} variable. | |
| 461 | |
| 462 A simple example demonstrating the use of structures within oct-files is | |
| 463 | |
| 9906 | 464 @example |
| 465 @EXAMPLEFILE(structdemo.cc) | |
| 466 @end example | |
| 6572 | 467 |
| 468 An example of its use is | |
| 469 | |
| 470 @example | |
| 471 @group | |
| 472 x.a = 1; x.b = "test"; x.c = [1, 2]; | |
| 473 structdemo (x, "b") | |
| 474 @result{} selected = test | |
| 475 @end group | |
| 476 @end example | |
| 477 | |
| 7001 | 478 The commented code above demonstrates how to iterate over all of the |
| 6572 | 479 fields of the structure, where as the following code demonstrates finding |
| 480 a particular field in a more concise manner. | |
| 481 | |
| 482 As can be seen the @code{contents} method of the @code{Octave_map} class | |
| 483 returns a @code{Cell} which allows structure arrays to be represented. | |
| 484 Therefore, to obtain the underlying @code{octave_value} we write | |
| 485 | |
| 486 @example | |
| 487 octave_value tmp = arg0.contents (p1) (0); | |
| 488 @end example | |
| 489 | |
|
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
490 @noindent |
| 6593 | 491 where the trailing (0) is the () operator on the @code{Cell} object. We |
| 492 can equally iterate of the elements of the Cell array to address the | |
| 493 elements of the structure array. | |
| 6572 | 494 |
| 495 @node Sparse Matrices in Oct-Files | |
| 496 @subsection Sparse Matrices in Oct-Files | |
| 6569 | 497 |
| 498 There are three classes of sparse objects that are of interest to the | |
| 499 user. | |
| 500 | |
| 6572 | 501 @table @code |
| 6569 | 502 @item SparseMatrix |
| 503 A double precision sparse matrix class | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
504 |
| 6569 | 505 @item SparseComplexMatrix |
| 506 A complex sparse matrix class | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
507 |
| 6569 | 508 @item SparseBoolMatrix |
| 509 A boolean sparse matrix class | |
| 510 @end table | |
| 511 | |
| 512 All of these classes inherit from the @code{Sparse<T>} template class, | |
| 6571 | 513 and so all have similar capabilities and usage. The @code{Sparse<T>} |
| 6569 | 514 class was based on Octave @code{Array<T>} class, and so users familiar |
| 6572 | 515 with Octave's @code{Array} classes will be comfortable with the use of |
| 6569 | 516 the sparse classes. |
| 517 | |
| 518 The sparse classes will not be entirely described in this section, due | |
| 6572 | 519 to their similarity with the existing @code{Array} classes. However, |
| 520 there are a few differences due the different nature of sparse objects, | |
| 521 and these will be described. Firstly, although it is fundamentally | |
| 522 possible to have N-dimensional sparse objects, the Octave sparse classes do | |
| 6571 | 523 not allow them at this time. So all operations of the sparse classes |
| 6569 | 524 must be 2-dimensional. This means that in fact @code{SparseMatrix} is |
| 525 similar to Octave's @code{Matrix} class rather than its | |
| 526 @code{NDArray} class. | |
| 527 | |
| 528 @menu | |
| 6572 | 529 * Array and Sparse Differences:: |
| 530 * Creating Sparse Matrices in Oct-Files:: | |
| 531 * Using Sparse Matrices in Oct-Files:: | |
| 6569 | 532 @end menu |
| 533 | |
| 6572 | 534 @node Array and Sparse Differences |
| 6569 | 535 @subsubsection The Differences between the Array and Sparse Classes |
| 536 | |
| 537 The number of elements in a sparse matrix is considered to be the number | |
| 6571 | 538 of non-zero elements rather than the product of the dimensions. Therefore |
| 6569 | 539 |
| 540 @example | |
| 6577 | 541 @group |
| 542 SparseMatrix sm; | |
| 543 @dots{} | |
| 544 int nel = sm.nelem (); | |
| 545 @end group | |
| 6569 | 546 @end example |
| 547 | |
|
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
548 @noindent |
| 6571 | 549 returns the number of non-zero elements. If the user really requires the |
| 6569 | 550 number of elements in the matrix, including the non-zero elements, they |
| 6571 | 551 should use @code{numel} rather than @code{nelem}. Note that for very |
| 7001 | 552 large matrices, where the product of the two dimensions is larger than |
| 553 the representation of an unsigned int, then @code{numel} can overflow. | |
| 6569 | 554 An example is @code{speye(1e6)} which will create a matrix with a million |
| 6571 | 555 rows and columns, but only a million non-zero elements. Therefore the |
| 6569 | 556 number of rows by the number of columns in this case is more than two |
| 557 hundred times the maximum value that can be represented by an unsigned int. | |
| 558 The use of @code{numel} should therefore be avoided useless it is known | |
| 559 it won't overflow. | |
| 560 | |
| 561 Extreme care must be take with the elem method and the "()" operator, | |
| 6571 | 562 which perform basically the same function. The reason is that if a |
| 6569 | 563 sparse object is non-const, then Octave will assume that a |
| 6571 | 564 request for a zero element in a sparse matrix is in fact a request |
| 565 to create this element so it can be filled. Therefore a piece of | |
| 6569 | 566 code like |
| 567 | |
| 568 @example | |
| 6577 | 569 @group |
| 570 SparseMatrix sm; | |
| 571 @dots{} | |
| 572 for (int j = 0; j < nc; j++) | |
| 573 for (int i = 0; i < nr; i++) | |
| 574 std::cerr << " (" << i << "," << j << "): " << sm(i,j) | |
| 575 << std::endl; | |
| 576 @end group | |
| 6569 | 577 @end example |
| 578 | |
|
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
579 @noindent |
| 6569 | 580 is a great way of turning the sparse matrix into a dense one, and a |
| 581 very slow way at that since it reallocates the sparse object at each | |
| 582 zero element in the matrix. | |
| 583 | |
| 584 An easy way of preventing the above from happening is to create a temporary | |
| 6571 | 585 constant version of the sparse matrix. Note that only the container for |
| 6569 | 586 the sparse matrix will be copied, while the actual representation of the |
| 6571 | 587 data will be shared between the two versions of the sparse matrix. So this |
| 588 is not a costly operation. For example, the above would become | |
| 6569 | 589 |
| 590 @example | |
| 6577 | 591 @group |
| 592 SparseMatrix sm; | |
| 593 @dots{} | |
| 594 const SparseMatrix tmp (sm); | |
| 595 for (int j = 0; j < nc; j++) | |
| 596 for (int i = 0; i < nr; i++) | |
| 597 std::cerr << " (" << i << "," << j << "): " << tmp(i,j) | |
| 598 << std::endl; | |
| 599 @end group | |
| 6569 | 600 @end example |
| 601 | |
| 602 Finally, as the sparse types aren't just represented as a contiguous | |
|
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
9906
diff
changeset
|
603 block of memory, the @nospell{@code{fortran_vec}} method of the @code{Array<T>} |
| 6571 | 604 is not available. It is however replaced by three separate methods |
| 6569 | 605 @code{ridx}, @code{cidx} and @code{data}, that access the raw compressed |
| 606 column format that the Octave sparse matrices are stored in. | |
| 607 Additionally, these methods can be used in a manner similar to @code{elem}, | |
| 6571 | 608 to allow the matrix to be accessed or filled. However, in that case it is |
| 6569 | 609 up to the user to respect the sparse matrix compressed column format |
| 610 discussed previous. | |
| 611 | |
| 6572 | 612 @node Creating Sparse Matrices in Oct-Files |
| 613 @subsubsection Creating Sparse Matrices in Oct-Files | |
| 6569 | 614 |
| 6572 | 615 You have several alternatives for creating a sparse matrix. |
| 616 You can first create the data as three vectors representing the | |
| 6569 | 617 row and column indexes and the data, and from those create the matrix. |
| 6572 | 618 Or alternatively, you can create a sparse matrix with the appropriate |
| 6571 | 619 amount of space and then fill in the values. Both techniques have their |
| 6569 | 620 advantages and disadvantages. |
| 621 | |
| 6572 | 622 Here is an example of how to create a small sparse matrix with the first |
| 623 technique | |
| 6569 | 624 |
| 625 @example | |
| 6577 | 626 @group |
| 627 int nz = 4, nr = 3, nc = 4; | |
| 628 | |
| 629 ColumnVector ridx (nz); | |
| 630 ColumnVector cidx (nz); | |
| 631 ColumnVector data (nz); | |
| 6569 | 632 |
| 6577 | 633 ridx(0) = 0; ridx(1) = 0; ridx(2) = 1; ridx(3) = 2; |
| 634 cidx(0) = 0; cidx(1) = 1; cidx(2) = 3; cidx(3) = 3; | |
| 635 data(0) = 1; data(1) = 2; data(2) = 3; data(3) = 4; | |
| 6569 | 636 |
| 6577 | 637 SparseMatrix sm (data, ridx, cidx, nr, nc); |
| 638 @end group | |
| 6569 | 639 @end example |
| 640 | |
| 6572 | 641 @noindent |
|
8817
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8486
diff
changeset
|
642 which creates the matrix given in section |
|
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8486
diff
changeset
|
643 @ref{Storage of Sparse Matrices}. Note that the compressed matrix |
|
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8486
diff
changeset
|
644 format is not used at the time of the creation of the matrix itself, |
|
03b7f618ab3d
include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents:
8486
diff
changeset
|
645 however it is used internally. |
| 6569 | 646 |
| 647 As previously mentioned, the values of the sparse matrix are stored | |
| 6571 | 648 in increasing column-major ordering. Although the data passed by the |
| 6569 | 649 user does not need to respect this requirement, the pre-sorting the |
| 650 data significantly speeds up the creation of the sparse matrix. | |
| 651 | |
| 652 The disadvantage of this technique of creating a sparse matrix is | |
| 6571 | 653 that there is a brief time where two copies of the data exists. Therefore |
| 6569 | 654 for extremely memory constrained problems this might not be the right |
| 655 technique to create the sparse matrix. | |
| 656 | |
| 657 The alternative is to first create the sparse matrix with the desired | |
| 6571 | 658 number of non-zero elements and then later fill those elements in. The |
| 659 easiest way to do this is | |
| 6569 | 660 |
| 6571 | 661 @example |
| 6577 | 662 @group |
| 663 int nz = 4, nr = 3, nc = 4; | |
| 664 SparseMatrix sm (nr, nc, nz); | |
| 665 sm(0,0) = 1; sm(0,1) = 2; sm(1,3) = 3; sm(2,3) = 4; | |
| 666 @end group | |
| 6569 | 667 @end example |
| 668 | |
| 6571 | 669 That creates the same matrix as previously. Again, although it is not |
| 6569 | 670 strictly necessary, it is significantly faster if the sparse matrix is |
| 671 created in this manner that the elements are added in column-major | |
| 6571 | 672 ordering. The reason for this is that if the elements are inserted |
| 6569 | 673 at the end of the current list of known elements then no element |
| 674 in the matrix needs to be moved to allow the new element to be | |
| 6571 | 675 inserted. Only the column indexes need to be updated. |
| 6569 | 676 |
| 677 There are a few further points to note about this technique of creating | |
| 6572 | 678 a sparse matrix. Firstly, it is possible to create a sparse matrix |
| 6571 | 679 with fewer elements than are actually inserted in the matrix. Therefore |
| 6569 | 680 |
| 6571 | 681 @example |
| 6577 | 682 @group |
| 683 int nz = 4, nr = 3, nc = 4; | |
| 684 SparseMatrix sm (nr, nc, 0); | |
| 685 sm(0,0) = 1; sm(0,1) = 2; sm(1,3) = 3; sm(2,3) = 4; | |
| 686 @end group | |
| 6569 | 687 @end example |
| 688 | |
| 6572 | 689 @noindent |
| 690 is perfectly valid. However it is a very bad idea. The reason is that | |
| 6569 | 691 as each new element is added to the sparse matrix the space allocated |
| 6571 | 692 to it is increased by reallocating the memory. This is an expensive |
| 6569 | 693 operation, that will significantly slow this means of creating a sparse |
| 6572 | 694 matrix. Furthermore, it is possible to create a sparse matrix with |
| 695 too much storage, so having @var{nz} above equaling 6 is also valid. | |
| 6569 | 696 The disadvantage is that the matrix occupies more memory than strictly |
| 697 needed. | |
| 698 | |
| 6572 | 699 It is not always easy to know the number of non-zero elements prior |
| 6571 | 700 to filling a matrix. For this reason the additional storage for the |
| 6569 | 701 sparse matrix can be removed after its creation with the |
| 6571 | 702 @dfn{maybe_compress} function. Furthermore, the maybe_compress can |
| 6569 | 703 deallocate the unused storage, but it can equally remove zero elements |
| 704 from the matrix. The removal of zero elements from the matrix is | |
| 705 controlled by setting the argument of the @dfn{maybe_compress} function | |
| 6572 | 706 to be @samp{true}. However, the cost of removing the zeros is high because it |
| 6571 | 707 implies resorting the elements. Therefore, if possible it is better |
| 708 is the user doesn't add the zeros in the first place. An example of | |
| 6569 | 709 the use of @dfn{maybe_compress} is |
| 710 | |
| 711 @example | |
| 6577 | 712 @group |
| 6569 | 713 int nz = 6, nr = 3, nc = 4; |
| 6577 | 714 |
| 6569 | 715 SparseMatrix sm1 (nr, nc, nz); |
| 716 sm1(0,0) = 1; sm1(0,1) = 2; sm1(1,3) = 3; sm1(2,3) = 4; | |
| 717 sm1.maybe_compress (); // No zero elements were added | |
| 718 | |
| 719 SparseMatrix sm2 (nr, nc, nz); | |
| 6571 | 720 sm2(0,0) = 1; sm2(0,1) = 2; sm(0,2) = 0; sm(1,2) = 0; |
| 6569 | 721 sm1(1,3) = 3; sm1(2,3) = 4; |
| 722 sm2.maybe_compress (true); // Zero elements were added | |
| 6577 | 723 @end group |
| 6569 | 724 @end example |
| 725 | |
| 726 The use of the @dfn{maybe_compress} function should be avoided if | |
| 727 possible, as it will slow the creation of the matrices. | |
| 728 | |
| 729 A third means of creating a sparse matrix is to work directly with | |
| 6571 | 730 the data in compressed row format. An example of this technique might |
| 6569 | 731 be |
| 732 | |
|
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
9906
diff
changeset
|
733 @c Note the @verbatim environment is a relatively new addition to Texinfo. |
| 6571 | 734 @c Therefore use the @example environment and replace @, with @@, |
| 6569 | 735 @c { with @{, etc |
| 736 | |
| 737 @example | |
| 6577 | 738 octave_value arg; |
| 739 @dots{} | |
| 740 int nz = 6, nr = 3, nc = 4; // Assume we know the max no nz | |
| 741 SparseMatrix sm (nr, nc, nz); | |
| 742 Matrix m = arg.matrix_value (); | |
| 6569 | 743 |
| 6577 | 744 int ii = 0; |
| 745 sm.cidx (0) = 0; | |
| 746 for (int j = 1; j < nc; j++) | |
| 747 @{ | |
| 748 for (int i = 0; i < nr; i++) | |
| 749 @{ | |
| 750 double tmp = foo (m(i,j)); | |
| 751 if (tmp != 0.) | |
| 752 @{ | |
| 753 sm.data(ii) = tmp; | |
| 754 sm.ridx(ii) = i; | |
| 755 ii++; | |
| 756 @} | |
| 757 @} | |
| 758 sm.cidx(j+1) = ii; | |
| 759 @} | |
| 7081 | 760 sm.maybe_compress (); // If don't know a-priori |
| 761 // the final no of nz. | |
| 6569 | 762 @end example |
| 763 | |
| 6572 | 764 @noindent |
| 6569 | 765 which is probably the most efficient means of creating the sparse matrix. |
| 766 | |
| 767 Finally, it might sometimes arise that the amount of storage initially | |
| 6571 | 768 created is insufficient to completely store the sparse matrix. Therefore, |
| 6569 | 769 the method @code{change_capacity} exists to reallocate the sparse memory. |
| 6571 | 770 The above example would then be modified as |
| 6569 | 771 |
| 772 @example | |
| 6577 | 773 octave_value arg; |
| 774 @dots{} | |
| 775 int nz = 6, nr = 3, nc = 4; // Assume we know the max no nz | |
| 776 SparseMatrix sm (nr, nc, nz); | |
| 777 Matrix m = arg.matrix_value (); | |
| 6569 | 778 |
| 6577 | 779 int ii = 0; |
| 780 sm.cidx (0) = 0; | |
| 781 for (int j = 1; j < nc; j++) | |
| 782 @{ | |
| 783 for (int i = 0; i < nr; i++) | |
| 784 @{ | |
| 785 double tmp = foo (m(i,j)); | |
| 786 if (tmp != 0.) | |
| 787 @{ | |
| 788 if (ii == nz) | |
| 789 @{ | |
| 790 nz += 2; // Add 2 more elements | |
| 791 sm.change_capacity (nz); | |
| 792 @} | |
| 793 sm.data(ii) = tmp; | |
| 794 sm.ridx(ii) = i; | |
| 795 ii++; | |
| 796 @} | |
| 797 @} | |
| 798 sm.cidx(j+1) = ii; | |
| 799 @} | |
| 7081 | 800 sm.maybe_mutate (); // If don't know a-priori |
| 801 // the final no of nz. | |
| 6569 | 802 @end example |
| 803 | |
| 804 Note that both increasing and decreasing the number of non-zero elements in | |
| 6571 | 805 a sparse matrix is expensive, as it involves memory reallocation. Also as |
| 6569 | 806 parts of the matrix, though not its entirety, exist as the old and new copy |
| 6571 | 807 at the same time, additional memory is needed. Therefore if possible this |
| 6569 | 808 should be avoided. |
| 809 | |
| 6572 | 810 @node Using Sparse Matrices in Oct-Files |
| 6569 | 811 @subsubsection Using Sparse Matrices in Oct-Files |
| 812 | |
| 813 Most of the same operators and functions on sparse matrices that are | |
| 814 available from the Octave are equally available with oct-files. | |
| 815 The basic means of extracting a sparse matrix from an @code{octave_value} | |
| 816 and returning them as an @code{octave_value}, can be seen in the | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
817 following example. |
| 6569 | 818 |
| 819 @example | |
| 6577 | 820 @group |
| 821 octave_value_list retval; | |
| 6569 | 822 |
| 6577 | 823 SparseMatrix sm = args(0).sparse_matrix_value (); |
| 7081 | 824 SparseComplexMatrix scm = |
| 825 args(1).sparse_complex_matrix_value (); | |
| 6577 | 826 SparseBoolMatrix sbm = args(2).sparse_bool_matrix_value (); |
| 827 @dots{} | |
| 828 retval(2) = sbm; | |
| 829 retval(1) = scm; | |
| 830 retval(0) = sm; | |
| 831 @end group | |
| 6569 | 832 @end example |
| 833 | |
| 834 The conversion to an octave-value is handled by the sparse | |
| 835 @code{octave_value} constructors, and so no special care is needed. | |
| 836 | |
| 837 @node Accessing Global Variables in Oct-Files | |
| 838 @subsection Accessing Global Variables in Oct-Files | |
| 839 | |
| 840 Global variables allow variables in the global scope to be | |
| 6571 | 841 accessed. Global variables can easily be accessed with oct-files using |
| 6569 | 842 the support functions @code{get_global_value} and |
| 6571 | 843 @code{set_global_value}. @code{get_global_value} takes two arguments, |
| 844 the first is a string representing the variable name to obtain. The | |
| 6569 | 845 second argument is a boolean argument specifying what to do in the case |
| 6571 | 846 that no global variable of the desired name is found. An example of the |
| 6569 | 847 use of these two functions is |
| 848 | |
| 9906 | 849 @example |
| 850 @EXAMPLEFILE(globaldemo.cc) | |
| 851 @end example | |
| 6569 | 852 |
| 853 An example of its use is | |
| 854 | |
| 855 @example | |
| 856 @group | |
| 857 global a b | |
| 858 b = 10; | |
| 859 globaldemo ("b") | |
| 860 @result{} 10 | |
| 861 globaldemo ("c") | |
| 862 @result{} "Global variable not found" | |
| 863 num2str (a) | |
| 864 @result{} 42 | |
| 865 @end group | |
| 866 @end example | |
| 867 | |
| 868 @node Calling Octave Functions from Oct-Files | |
| 869 @subsection Calling Octave Functions from Oct-Files | |
| 870 | |
| 871 There is often a need to be able to call another octave function from | |
| 872 within an oct-file, and there are many examples of such within octave | |
| 6571 | 873 itself. For example the @code{quad} function is an oct-file that |
| 6569 | 874 calculates the definite integral by quadrature over a user supplied |
| 875 function. | |
| 876 | |
| 6571 | 877 There are also many ways in which a function might be passed. It might |
| 878 be passed as one of | |
| 6569 | 879 |
| 880 @enumerate 1 | |
| 881 @item Function Handle | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
882 |
| 6569 | 883 @item Anonymous Function Handle |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
884 |
| 6569 | 885 @item Inline Function |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
886 |
| 6569 | 887 @item String |
| 888 @end enumerate | |
| 889 | |
| 890 The example below demonstrates an example that accepts all four means of | |
| 6571 | 891 passing a function to an oct-file. |
| 6569 | 892 |
| 9906 | 893 @example |
| 894 @EXAMPLEFILE(funcdemo.cc) | |
| 895 @end example | |
| 6569 | 896 |
| 897 The first argument to this demonstration is the user supplied function | |
| 898 and the following arguments are all passed to the user function. | |
| 899 | |
| 900 @example | |
| 901 @group | |
| 6572 | 902 funcdemo (@@sin,1) |
| 6569 | 903 @result{} 0.84147 |
| 6572 | 904 funcdemo (@@(x) sin(x), 1) |
| 6569 | 905 @result{} 0.84147 |
| 6572 | 906 funcdemo (inline ("sin(x)"), 1) |
| 6569 | 907 @result{} 0.84147 |
| 6572 | 908 funcdemo ("sin",1) |
| 6569 | 909 @result{} 0.84147 |
| 910 funcdemo (@@atan2, 1, 1) | |
| 911 @result{} 0.78540 | |
| 912 @end group | |
| 913 @end example | |
| 914 | |
| 915 When the user function is passed as a string, the treatment of the | |
| 6571 | 916 function is different. In some cases it is necessary to always have the |
| 6572 | 917 user supplied function as an @code{octave_function} object. In that |
| 918 case the string argument can be used to create a temporary function like | |
| 6569 | 919 |
| 920 @example | |
| 921 @group | |
| 6577 | 922 std::octave fcn_name = unique_symbol_name ("__fcn__"); |
| 923 std::string fname = "function y = "; | |
| 924 fname.append (fcn_name); | |
| 925 fname.append ("(x) y = "); | |
| 926 fcn = extract_function (args(0), "funcdemo", fcn_name, | |
| 927 fname, "; endfunction"); | |
| 928 @dots{} | |
| 929 if (fcn_name.length ()) | |
| 930 clear_function (fcn_name); | |
| 6569 | 931 @end group |
| 932 @end example | |
| 933 | |
| 6571 | 934 There are two important things to know in this case. The number of input |
| 6569 | 935 arguments to the user function is fixed, and in the above is a single |
| 936 argument, and secondly to avoid leaving the temporary function in the | |
| 937 Octave symbol table it should be cleared after use. | |
| 938 | |
| 939 @node Calling External Code from Oct-Files | |
| 940 @subsection Calling External Code from Oct-Files | |
| 941 | |
| 942 Linking external C code to Octave is relatively simple, as the C | |
| 6571 | 943 functions can easily be called directly from C++. One possible issue is |
| 6569 | 944 the declarations of the external C functions might need to be explicitly |
| 6571 | 945 defined as C functions to the compiler. If the declarations of the |
| 6569 | 946 external C functions are in the header @code{foo.h}, then the manner in |
| 947 which to ensure that the C++ compiler treats these declarations as C | |
| 948 code is | |
| 949 | |
| 950 @example | |
| 951 @group | |
| 952 #ifdef __cplusplus | |
| 6571 | 953 extern "C" |
| 6569 | 954 @{ |
| 955 #endif | |
| 956 #include "foo.h" | |
| 957 #ifdef __cplusplus | |
| 958 @} /* end extern "C" */ | |
| 959 #endif | |
| 960 @end group | |
| 961 @end example | |
| 962 | |
| 6571 | 963 Calling Fortran code however can pose some difficulties. This is due to |
| 6569 | 964 differences in the manner in compilers treat the linking of Fortran code |
| 6571 | 965 with C or C++ code. Octave supplies a number of macros that allow |
| 6569 | 966 consistent behavior across a number of compilers. |
| 967 | |
| 968 The underlying Fortran code should use the @code{XSTOPX} function to | |
| 6571 | 969 replace the Fortran @code{STOP} function. @code{XSTOPX} uses the Octave |
|
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
9906
diff
changeset
|
970 exception handler to treat failing cases in the Fortran code |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
971 explicitly. Note that Octave supplies its own replacement @sc{blas} |
| 6569 | 972 @code{XERBLA} function, which uses @code{XSTOPX}. |
| 973 | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
974 If the underlying code calls @code{XSTOPX}, then the @w{@code{F77_XFCN}} |
|
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
9906
diff
changeset
|
975 macro should be used to call the underlying Fortran function. The Fortran |
| 6569 | 976 exception state can then be checked with the global variable |
| 6572 | 977 @code{f77_exception_encountered}. If @code{XSTOPX} will not be called, |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
978 then the @w{@code{F77_FCN}} macro should be used instead to call the Fortran |
| 6569 | 979 code. |
| 980 | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
981 There is no harm in using @w{@code{F77_XFCN}} in all cases, except that for |
| 6569 | 982 Fortran code that is short running and executes a large number of times, |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
983 there is potentially an overhead in doing so. However, if @w{@code{F77_FCN}} |
| 6569 | 984 is used with code that calls @code{XSTOP}, Octave can generate a |
| 985 segmentation fault. | |
| 986 | |
| 987 An example of the inclusion of a Fortran function in an oct-file is | |
| 988 given in the following example, where the C++ wrapper is | |
| 989 | |
| 9906 | 990 @example |
| 991 @EXAMPLEFILE(fortdemo.cc) | |
| 992 @end example | |
| 6569 | 993 |
| 6572 | 994 @noindent |
|
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
9906
diff
changeset
|
995 and the Fortran function is |
| 6569 | 996 |
| 9906 | 997 @example |
| 998 @EXAMPLEFILE(fortsub.f) | |
| 999 @end example | |
| 6569 | 1000 |
| 1001 This example demonstrates most of the features needed to link to an | |
| 1002 external Fortran function, including passing arrays and strings, as well | |
| 6571 | 1003 as exception handling. An example of the behavior of this function is |
| 6569 | 1004 |
| 1005 @example | |
| 1006 @group | |
| 6572 | 1007 [b, s] = fortdemo (1:3) |
| 6569 | 1008 @result{} |
| 1009 b = 1.00000 0.50000 0.33333 | |
| 1010 s = There are 3 values in the input vector | |
| 1011 [b, s] = fortdemo(0:3) | |
| 1012 error: fortsub:divide by zero | |
| 1013 error: exception encountered in Fortran subroutine fortsub_ | |
|
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
9906
diff
changeset
|
1014 error: fortdemo: error in Fortran |
| 6569 | 1015 @end group |
| 1016 @end example | |
| 1017 | |
| 1018 @node Allocating Local Memory in Oct-Files | |
| 1019 @subsection Allocating Local Memory in Oct-Files | |
| 1020 | |
| 1021 Allocating memory within an oct-file might seem easy as the C++ | |
| 6571 | 1022 new/delete operators can be used. However, in that case care must be |
| 1023 taken to avoid memory leaks. The preferred manner in which to allocate | |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
1024 memory for use locally is to use the @w{@code{OCTAVE_LOCAL_BUFFER}} macro. |
| 6572 | 1025 An example of its use is |
| 6569 | 1026 |
| 1027 @example | |
| 1028 OCTAVE_LOCAL_BUFFER (double, tmp, len) | |
| 1029 @end example | |
| 1030 | |
|
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10828
diff
changeset
|
1031 @noindent |
| 6569 | 1032 that returns a pointer @code{tmp} of type @code{double *} of length |
| 1033 @code{len}. | |
| 1034 | |
| 1035 @node Input Parameter Checking in Oct-Files | |
| 1036 @subsection Input Parameter Checking in Oct-Files | |
| 1037 | |
| 6580 | 1038 As oct-files are compiled functions they have the possibility of causing |
| 7001 | 1039 Octave to abort abnormally. It is therefore important that |
| 1040 each and every function has the minimum of parameter | |
| 6580 | 1041 checking needed to ensure that Octave behaves well. |
| 1042 | |
| 1043 The minimum requirement, as previously discussed, is to check the number | |
| 1044 of input arguments before using them to avoid referencing a non existent | |
| 1045 argument. However, it some case this might not be sufficient as the | |
| 6593 | 1046 underlying code imposes further constraints. For example an external |
| 6580 | 1047 function call might be undefined if the input arguments are not |
| 6593 | 1048 integers, or if one of the arguments is zero. Therefore, oct-files often |
| 6580 | 1049 need additional input parameter checking. |
| 1050 | |
| 1051 There are several functions within Octave that might be useful for the | |
| 6593 | 1052 purposes of parameter checking. These include the methods of the |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1053 octave_value class like @code{is_real_matrix}, etc., but equally include |
| 6593 | 1054 more specialized functions. Some of the more common ones are |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1055 demonstrated in the following example. |
| 6580 | 1056 |
| 9906 | 1057 @example |
| 1058 @EXAMPLEFILE(paramdemo.cc) | |
| 1059 @end example | |
| 6580 | 1060 |
| 1061 @noindent | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1062 An example of its use is: |
| 6580 | 1063 |
| 1064 @example | |
| 1065 @group | |
| 1066 paramdemo ([1, 2, NaN, Inf]) | |
| 1067 @result{} Properties of input array: | |
| 1068 includes Inf or NaN values | |
| 1069 includes other values than 1 and 0 | |
| 1070 includes only int, Inf or NaN values | |
| 1071 @end group | |
| 1072 @end example | |
| 6569 | 1073 |
| 1074 @node Exception and Error Handling in Oct-Files | |
| 1075 @subsection Exception and Error Handling in Oct-Files | |
| 1076 | |
| 1077 Another important feature of Octave is its ability to react to the user | |
| 6571 | 1078 typing @kbd{Control-C} even during calculations. This ability is based on the |
| 6569 | 1079 C++ exception handler, where memory allocated by the C++ new/delete |
| 6571 | 1080 methods are automatically released when the exception is treated. When |
| 6569 | 1081 writing an oct-file, to allow Octave to treat the user typing @kbd{Control-C}, |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1082 the @w{@code{OCTAVE_QUIT}} macro is supplied. For example: |
| 6569 | 1083 |
| 1084 @example | |
| 1085 @group | |
| 6577 | 1086 for (octave_idx_type i = 0; i < a.nelem (); i++) |
| 1087 @{ | |
| 1088 OCTAVE_QUIT; | |
| 1089 b.elem(i) = 2. * a.elem(i); | |
| 1090 @} | |
| 6569 | 1091 @end group |
| 1092 @end example | |
| 1093 | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1094 The presence of the @w{@code{OCTAVE_QUIT}} macro in the inner loop allows |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1095 Octave to treat the user request with the @kbd{Control-C}. Without this macro, |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1096 the user must either wait for the function to return before the interrupt is |
| 6569 | 1097 processed, or press @kbd{Control-C} three times to force Octave to exit. |
| 1098 | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1099 The @w{@code{OCTAVE_QUIT}} macro does impose a very small speed penalty, and so |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1100 for loops that are known to be small it might not make sense to include |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
1101 @w{@code{OCTAVE_QUIT}}. |
| 6569 | 1102 |
| 1103 When creating an oct-file that uses an external libraries, the function | |
| 1104 might spend a significant portion of its time in the external | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1105 library. It is not generally possible to use the @w{@code{OCTAVE_QUIT}} macro |
|
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1106 in this case. The alternative in this case is |
| 6569 | 1107 |
| 1108 @example | |
| 1109 @group | |
| 6577 | 1110 BEGIN_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE; |
| 1111 @dots{} some code that calls a "foreign" function @dots{} | |
| 1112 END_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE; | |
| 6569 | 1113 @end group |
| 1114 @end example | |
| 1115 | |
| 1116 The disadvantage of this is that if the foreign code allocates any | |
| 1117 memory internally, then this memory might be lost during an interrupt, | |
| 6571 | 1118 without being deallocated. Therefore, ideally Octave itself should |
| 6569 | 1119 allocate any memory that is needed by the foreign code, with either the |
|
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
9906
diff
changeset
|
1120 @nospell{fortran_vec} method or the @w{@code{OCTAVE_LOCAL_BUFFER}} macro. |
| 6569 | 1121 |
|
9038
fca0dc2fb042
Cleanup documentation files stmt.texi and func.texi
Rik <rdrider0-list@yahoo.com>
parents:
8920
diff
changeset
|
1122 The Octave unwind_protect mechanism (@ref{The @code{unwind_protect} Statement}) |
| 6571 | 1123 can also be used in oct-files. In conjunction with the exception |
| 6569 | 1124 handling of Octave, it is important to enforce that certain code is run |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1125 to allow variables, etc. to be restored even if an exception occurs. An |
| 6569 | 1126 example of the use of this mechanism is |
| 1127 | |
| 9906 | 1128 @example |
| 1129 @EXAMPLEFILE(unwinddemo.cc) | |
| 1130 @end example | |
| 6569 | 1131 |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1132 As can be seen in the example: |
| 6569 | 1133 |
| 1134 @example | |
| 1135 @group | |
| 6572 | 1136 unwinddemo (1, 0) |
| 6569 | 1137 @result{} Inf |
| 1138 1 / 0 | |
| 1139 @result{} warning: division by zero | |
| 6593 | 1140 Inf |
| 6569 | 1141 @end group |
| 1142 @end example | |
| 1143 | |
| 1144 The division by zero (and in fact all warnings) is disabled in the | |
| 1145 @code{unwinddemo} function. | |
| 1146 | |
| 1147 @node Documentation and Test of Oct-Files | |
| 1148 @subsection Documentation and Test of Oct-Files | |
| 1149 | |
| 6580 | 1150 The documentation of an oct-file is the fourth string parameter of the |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
1151 @w{@code{DEFUN_DLD}} macro. This string can be formatted in the same manner |
| 6580 | 1152 as the help strings for user functions (@ref{Documentation Tips}), |
| 1153 however there are some issue that are particular to the formatting of | |
| 1154 help strings within oct-files. | |
| 1155 | |
| 1156 The major issue is that the help string will typically be longer than a | |
| 1157 single line of text, and so the formatting of long help strings need to | |
| 7001 | 1158 be taken into account. There are several manners in which to treat this |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1159 issue, but the most common is illustrated in the following example, |
| 6580 | 1160 |
| 1161 @example | |
| 1162 @group | |
| 1163 DEFUN_DLD (do_what_i_want, args, nargout, | |
| 1164 "-*- texinfo -*-\n\ | |
| 1165 @@deftypefn @{Function File@} @{@} do_what_i_say (@@var@{n@})\n\ | |
| 7081 | 1166 A function that does what the user actually wants rather\n\ |
| 1167 than what they requested.\n\ | |
| 6580 | 1168 @@end deftypefn") |
| 1169 @{ | |
| 1170 @dots{} | |
| 1171 @} | |
| 1172 @end group | |
| 1173 @end example | |
| 1174 | |
| 1175 @noindent | |
| 1176 where, as can be seen, end line of text within the help string is | |
|
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
8097
diff
changeset
|
1177 terminated by @code{\n\} which is an embedded new-line in the string |
| 6580 | 1178 together with a C++ string continuation character. Note that the final |
| 1179 @code{\} must be the last character on the line. | |
| 1180 | |
| 1181 Octave also includes the ability to embed the test and demonstration | |
| 1182 code for a function within the code itself (@ref{Test and Demo Functions}). | |
| 1183 This can be used from within oct-files (or in fact any file) with | |
| 1184 certain provisos. Firstly, the test and demo functions of Octave look | |
| 1185 for a @code{%!} as the first characters on a new-line to identify test | |
| 1186 and demonstration code. This is equally a requirement for | |
| 1187 oct-files. Furthermore the test and demonstration code must be included | |
| 1188 in a comment block of the compiled code to avoid it being interpreted by | |
| 6606 | 1189 the compiler. Finally, the Octave test and demonstration code must have |
| 6580 | 1190 access to the source code of the oct-file and not just the compiled code |
| 6606 | 1191 as the tests are stripped from the compiled code. An example in an |
| 6580 | 1192 oct-file might be |
| 1193 | |
| 1194 @example | |
| 1195 @group | |
| 1196 /* | |
| 1197 | |
| 1198 %!error (sin()) | |
| 1199 %!error (sin(1,1)) | |
| 1200 %!assert (sin([1,2]),[sin(1),sin(2)]) | |
| 1201 | |
| 1202 */ | |
| 1203 @end group | |
| 1204 @end example | |
| 6569 | 1205 |
| 6593 | 1206 @c @node Application Programming Interface for Oct-Files |
| 1207 @c @subsection Application Programming Interface for Oct-Files | |
| 1208 @c | |
| 1209 @c WRITE ME, using Coda section 1.3 as a starting point. | |
| 6569 | 1210 |
| 1211 @node Mex-Files | |
| 1212 @section Mex-Files | |
| 1213 @cindex mex-files | |
| 1214 @cindex mex | |
| 1215 | |
| 1216 Octave includes an interface to allow legacy mex-files to be compiled | |
|
11573
6f8ffe2c6f76
Grammarcheck txi files for 3.4 release.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
1217 and used with Octave. This interface can also be used to share code |
|
6f8ffe2c6f76
Grammarcheck txi files for 3.4 release.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
1218 between Octave and @sc{matlab} users. However, as mex-files expose the |
|
6f8ffe2c6f76
Grammarcheck txi files for 3.4 release.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
1219 @sc{matlab}'s internal API, and the internal structure of Octave is |
|
11479
746609dd54fd
Remove Matlab euphemisms in docs and use @file macro for filenames
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
10846
diff
changeset
|
1220 different, a mex-file can never have the same performance in Octave as |
|
11573
6f8ffe2c6f76
Grammarcheck txi files for 3.4 release.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
1221 the equivalent oct-file. In particular to support the manner in which |
|
11479
746609dd54fd
Remove Matlab euphemisms in docs and use @file macro for filenames
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
10846
diff
changeset
|
1222 mex-files access the variables passed to mex functions, there are a |
|
746609dd54fd
Remove Matlab euphemisms in docs and use @file macro for filenames
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
10846
diff
changeset
|
1223 significant number of additional copies of memory when calling or |
|
11573
6f8ffe2c6f76
Grammarcheck txi files for 3.4 release.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
1224 returning from a mex function. For this reason, new code should be |
|
11479
746609dd54fd
Remove Matlab euphemisms in docs and use @file macro for filenames
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
10846
diff
changeset
|
1225 written using the oct-file interface discussed above if possible. |
| 6569 | 1226 |
| 1227 @menu | |
| 6572 | 1228 * Getting Started with Mex-Files:: |
| 6580 | 1229 * Working with Matrices and Arrays in Mex-Files:: |
| 1230 * Character Strings in Mex-Files:: | |
| 1231 * Cell Arrays with Mex-Files:: | |
| 6572 | 1232 * Structures with Mex-Files:: |
| 1233 * Sparse Matrices with Mex-Files:: | |
| 6580 | 1234 * Calling Other Functions in Mex-Files:: |
| 6593 | 1235 @c * Application Programming Interface for Mex-Files:: |
| 6569 | 1236 @end menu |
| 1237 | |
| 1238 @node Getting Started with Mex-Files | |
| 1239 @subsection Getting Started with Mex-Files | |
| 1240 | |
|
11479
746609dd54fd
Remove Matlab euphemisms in docs and use @file macro for filenames
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
10846
diff
changeset
|
1241 The basic command to build a mex-file is either @code{mkoctfile --mex} |
|
11573
6f8ffe2c6f76
Grammarcheck txi files for 3.4 release.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
1242 or @code{mex}. The first can either be used from within Octave or from |
|
6f8ffe2c6f76
Grammarcheck txi files for 3.4 release.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
1243 the command line. However, to avoid issues with @sc{matlab}'s own @code{mex} |
|
11479
746609dd54fd
Remove Matlab euphemisms in docs and use @file macro for filenames
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
10846
diff
changeset
|
1244 command, the use of the command @code{mex} is limited to within Octave. |
| 6569 | 1245 |
| 1246 @DOCSTRING(mex) | |
| 1247 | |
| 1248 @DOCSTRING(mexext) | |
| 1249 | |
|
11573
6f8ffe2c6f76
Grammarcheck txi files for 3.4 release.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
1250 One important difference with the use of @code{mex} between @sc{matlab} and |
|
11479
746609dd54fd
Remove Matlab euphemisms in docs and use @file macro for filenames
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
10846
diff
changeset
|
1251 Octave is that the header file "matrix.h" is implicitly included through |
|
11573
6f8ffe2c6f76
Grammarcheck txi files for 3.4 release.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
1252 the inclusion of "mex.h". This is to avoid a conflict with the Octave |
|
11479
746609dd54fd
Remove Matlab euphemisms in docs and use @file macro for filenames
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
10846
diff
changeset
|
1253 file "Matrix.h" with operating systems and compilers that don't |
| 6569 | 1254 distinguish between filenames in upper and lower case |
| 1255 | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1256 Consider the short example: |
| 6569 | 1257 |
| 9906 | 1258 @example |
| 1259 @group | |
| 1260 @EXAMPLEFILE(firstmexdemo.c) | |
| 1261 @end group | |
| 1262 @end example | |
| 6569 | 1263 |
| 6593 | 1264 This simple example demonstrates the basics of writing a mex-file. The |
| 1265 entry point into the mex-file is defined by @code{mexFunction}. Note | |
| 6580 | 1266 that the function name is not explicitly included in the |
| 1267 @code{mexFunction} and so there can only be a single @code{mexFunction} | |
| 1268 entry point per-file. Also the name of the function is determined by the | |
| 1269 name of the mex-file itself. Therefore if the above function is in the | |
| 1270 file @file{firstmexdemo.c}, it can be compiled with | |
| 1271 | |
| 1272 @example | |
| 1273 mkoctfile --mex firstmexdemo.c | |
| 1274 @end example | |
| 1275 | |
| 1276 @noindent | |
| 1277 which creates a file @file{firstmexdemo.mex}. The function can then be run | |
| 1278 from Octave as | |
| 1279 | |
| 1280 @example | |
| 1281 @group | |
| 1282 firstmexdemo() | |
| 1283 @result{} 1.2346 | |
| 1284 @end group | |
| 1285 @end example | |
| 1286 | |
| 1287 It should be noted that the mex-file contains no help string for the | |
| 6593 | 1288 functions it contains. To document mex-files, there should exist an |
| 1289 m-file in the same directory as the mex-file itself. Taking the above as | |
| 6580 | 1290 an example, we would therefore have a file @file{firstmexdemo.m} that might |
| 1291 contain the text | |
| 1292 | |
| 1293 @example | |
| 1294 %FIRSTMEXDEMO Simple test of the functionality of a mex-file. | |
| 1295 @end example | |
| 1296 | |
| 1297 In this case, the function that will be executed within Octave will be | |
| 1298 given by the mex-file, while the help string will come from the | |
| 6593 | 1299 m-file. This can also be useful to allow a sample implementation of the |
| 6580 | 1300 mex-file within the Octave language itself for testing purposes. |
| 1301 | |
|
8347
fa78cb8d8a5c
corrections for typos
Brian Gough<bjg@network-theory.co.uk>
parents:
8097
diff
changeset
|
1302 Although we cannot have multiple entry points into a single mex-file, |
| 6580 | 1303 we can use the @code{mexFunctionName} function to determine what name |
| 6593 | 1304 the mex-file was called with. This can be used to alter the behavior of |
| 1305 the mex-file based on the function name. For example if | |
| 6580 | 1306 |
| 9906 | 1307 @example |
| 1308 @group | |
| 1309 @EXAMPLEFILE(myfunc.c) | |
| 1310 @end group | |
| 1311 @end example | |
| 6580 | 1312 |
| 1313 @noindent | |
| 1314 is in file @file{myfunc.c}, and it is compiled with | |
| 1315 | |
| 1316 @example | |
| 1317 @group | |
| 1318 mkoctfile --mex myfunc.c | |
| 1319 ln -s myfunc.mex myfunc2.mex | |
| 1320 @end group | |
| 1321 @end example | |
| 1322 | |
| 1323 Then as can be seen by | |
| 1324 | |
| 1325 @example | |
| 1326 @group | |
| 1327 myfunc() | |
| 1328 @result{} You called function: myfunc | |
| 1329 This is the principal function | |
| 1330 myfunc2() | |
| 1331 @result{} You called function: myfunc2 | |
| 1332 @end group | |
| 1333 @end example | |
| 1334 | |
| 1335 @noindent | |
| 1336 the behavior of the mex-file can be altered depending on the functions | |
| 1337 name. | |
| 1338 | |
| 6593 | 1339 Allow the user should only include @code{mex.h} in their code, Octave |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1340 declares additional functions, typedefs, etc., available to the user to |
| 6593 | 1341 write mex-files in the headers @code{mexproto.h} and @code{mxarray.h}. |
| 1342 | |
| 6580 | 1343 @node Working with Matrices and Arrays in Mex-Files |
| 1344 @subsection Working with Matrices and Arrays in Mex-Files | |
| 1345 | |
| 6593 | 1346 The basic mex type of all variables is @code{mxArray}. All variables, |
| 1347 such as matrices, cell arrays or structures are all stored in this basic | |
| 6580 | 1348 type, and this type serves basically the same purpose as the |
| 6593 | 1349 octave_value class in oct-files. That is it acts as a container for the |
| 6580 | 1350 more specialized types. |
| 1351 | |
| 6593 | 1352 The @code{mxArray} structure contains at a minimum, the variable it |
| 1353 represents name, its dimensions, its type and whether the variable is | |
| 1354 real or complex. It can however contain a number of additional fields | |
| 1355 depending on the type of the @code{mxArray}. There are a number of | |
| 1356 functions to create @code{mxArray} structures, including | |
| 1357 @code{mxCreateCellArray}, @code{mxCreateSparse} and the generic | |
| 1358 @code{mxCreateNumericArray}. | |
| 1359 | |
| 1360 The basic functions to access the data contained in an array is | |
| 1361 @code{mxGetPr}. As the mex interface assumes that the real and imaginary | |
| 6939 | 1362 parts of a complex array are stored separately, there is an equivalent |
| 6593 | 1363 function @code{mxGetPi} that get the imaginary part. Both of these |
| 1364 functions are for use only with double precision matrices. There also | |
| 1365 exists the generic function @code{mxGetData} and @code{mxGetImagData} | |
|
10828
322f43e0e170
Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
1366 that perform the same operation on all matrix types. For example: |
| 6593 | 1367 |
| 1368 @example | |
| 1369 @group | |
| 1370 mxArray *m; | |
| 6686 | 1371 mwSize *dims; |
| 6593 | 1372 UINT32_T *pr; |
| 1373 | |
| 6686 | 1374 dims = (mwSize *) mxMalloc (2 * sizeof(mwSize)); |
| 6593 | 1375 dims[0] = 2; |
| 1376 dims[1] = 2; | |
| 1377 m = mxCreateNumericArray (2, dims, mxUINT32_CLASS, mxREAL); | |
| 1378 pr = = (UINT32_T *) mxGetData (m); | |
| 1379 @end group | |
| 1380 @end example | |
| 1381 | |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1382 There are also the functions @code{mxSetPr}, etc., that perform the |
| 6593 | 1383 inverse, and set the data of an Array to use the block of memory pointed |
| 1384 to by the argument of @code{mxSetPr}. | |
| 1385 | |
| 6686 | 1386 Note the type @code{mwSize} used above, and @code{mwIndex} are defined |
| 1387 as the native precision of the indexing in Octave on the platform on | |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1388 which the mex-file is built. This allows both 32- and 64-bit platforms |
|
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1389 to support mex-files. @code{mwSize} is used to define array dimension |
| 6686 | 1390 and maximum number or elements, while @code{mwIndex} is used to define |
| 1391 indexing into arrays. | |
| 1392 | |
| 6593 | 1393 An example that demonstration how to work with arbitrary real or complex |
| 1394 double precision arrays is given by the file @file{mypow2.c} as given | |
| 1395 below. | |
| 1396 | |
| 9906 | 1397 @example |
| 1398 @EXAMPLEFILE(mypow2.c) | |
| 1399 @end example | |
| 6593 | 1400 |
| 1401 @noindent | |
| 1402 with an example of its use | |
| 1403 | |
| 1404 @example | |
| 1405 @group | |
| 1406 b = randn(4,1) + 1i * randn(4,1); | |
| 1407 all(b.^2 == mypow2(b)) | |
| 1408 @result{} 1 | |
| 1409 @end group | |
| 1410 @end example | |
| 1411 | |
| 1412 | |
| 7096 | 1413 The example above uses the functions @code{mxGetDimensions}, |
| 1414 @code{mxGetNumberOfElements}, and @code{mxGetNumberOfDimensions} to work | |
| 1415 with the dimensions of multi-dimensional arrays. The functions | |
| 1416 @code{mxGetM}, and @code{mxGetN} are also available to find the number | |
| 1417 of rows and columns in a matrix. | |
| 6580 | 1418 |
| 1419 @node Character Strings in Mex-Files | |
| 1420 @subsection Character Strings in Mex-Files | |
| 1421 | |
| 6593 | 1422 As mex-files do not make the distinction between single and double |
| 1423 quoted strings within Octave, there is perhaps less complexity in the | |
| 1424 use of strings and character matrices in mex-files. An example of their | |
| 1425 use, that parallels the demo in @file{stringdemo.cc}, is given in the | |
| 1426 file @file{mystring.c}, as seen below. | |
| 1427 | |
| 9906 | 1428 @example |
| 1429 @EXAMPLEFILE(mystring.c) | |
| 1430 @end example | |
| 6593 | 1431 |
| 1432 @noindent | |
| 1433 An example of its expected output is | |
| 1434 | |
| 1435 @example | |
| 1436 @group | |
| 1437 mystring(["First String"; "Second String"]) | |
| 1438 @result{} s1 = Second String | |
| 1439 First String | |
| 1440 @end group | |
| 1441 @end example | |
| 1442 | |
| 7096 | 1443 Other functions in the mex interface for handling character strings are |
| 1444 @code{mxCreateString}, @code{mxArrayToString}, and | |
| 1445 @code{mxCreateCharMatrixFromStrings}. In a mex-file, a character string | |
| 1446 is considered to be a vector rather than a matrix. This is perhaps an | |
| 1447 arbitrary distinction as the data in the mxArray for the matrix is | |
| 1448 consecutive in any case. | |
| 6580 | 1449 |
| 1450 @node Cell Arrays with Mex-Files | |
| 1451 @subsection Cell Arrays with Mex-Files | |
| 6569 | 1452 |
| 6593 | 1453 We can perform exactly the same operations in Cell arrays in mex-files |
| 1454 as we can in oct-files. An example that reduplicates the functional of | |
| 1455 the @file{celldemo.cc} oct-file in a mex-file is given by | |
| 1456 @file{mycell.c} as below | |
| 1457 | |
| 9906 | 1458 @example |
| 1459 @group | |
| 1460 @EXAMPLEFILE(mycell.c) | |
| 1461 @end group | |
| 1462 @end example | |
| 6593 | 1463 |
| 1464 @noindent | |
| 1465 which as can be seen below has exactly the same behavior as the oct-file | |
| 1466 version. | |
| 1467 | |
| 1468 @example | |
| 1469 @group | |
| 1470 [b1, b2, b3] = mycell (@{1, [1, 2], "test"@}) | |
| 1471 @result{} | |
| 1472 b1 = 1 | |
| 1473 b2 = | |
| 1474 | |
| 1475 1 2 | |
| 1476 | |
| 1477 b3 = test | |
| 1478 @end group | |
| 1479 @end example | |
| 1480 | |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1481 Note in the example the use of the @code{mxDuplicateArray} function. This |
| 6593 | 1482 is needed as the @code{mxArray} pointer returned by @code{mxGetCell} |
| 1483 might be deallocated. The inverse function to @code{mxGetCell} is | |
| 1484 @code{mcSetCell} and is defined as | |
| 1485 | |
| 1486 @example | |
| 1487 void mxSetCell (mxArray *ptr, int idx, mxArray *val); | |
| 1488 @end example | |
| 1489 | |
| 7007 | 1490 Finally, to create a cell array or matrix, the appropriate functions are |
| 6593 | 1491 |
| 1492 @example | |
| 1493 @group | |
| 1494 mxArray *mxCreateCellArray (int ndims, const int *dims); | |
| 1495 mxArray *mxCreateCellMatrix (int m, int n); | |
| 1496 @end group | |
| 1497 @end example | |
| 6569 | 1498 |
| 6572 | 1499 @node Structures with Mex-Files |
| 1500 @subsection Structures with Mex-Files | |
| 6569 | 1501 |
| 6593 | 1502 The basic function to create a structure in a mex-file is |
| 1503 @code{mxCreateStructMatrix}, which creates a structure array with a two | |
| 1504 dimensional matrix, or @code{mxCreateStructArray}. | |
| 1505 | |
| 1506 @example | |
| 1507 @group | |
| 7081 | 1508 mxArray *mxCreateStructArray (int ndims, int *dims, |
| 1509 int num_keys, | |
| 6593 | 1510 const char **keys); |
| 7081 | 1511 mxArray *mxCreateStructMatrix (int rows, int cols, |
| 1512 int num_keys, | |
| 6593 | 1513 const char **keys); |
| 1514 @end group | |
| 1515 @end example | |
| 1516 | |
| 1517 Accessing the fields of the structure can then be performed with the | |
| 1518 @code{mxGetField} and @code{mxSetField} or alternatively with the | |
| 1519 @code{mxGetFieldByNumber} and @code{mxSetFieldByNumber} functions. | |
| 1520 | |
| 1521 @example | |
| 1522 @group | |
| 7081 | 1523 mxArray *mxGetField (const mxArray *ptr, mwIndex index, |
| 1524 const char *key); | |
| 6593 | 1525 mxArray *mxGetFieldByNumber (const mxArray *ptr, |
| 6686 | 1526 mwIndex index, int key_num); |
| 1527 void mxSetField (mxArray *ptr, mwIndex index, | |
| 6593 | 1528 const char *key, mxArray *val); |
| 6686 | 1529 void mxSetFieldByNumber (mxArray *ptr, mwIndex index, |
| 6593 | 1530 int key_num, mxArray *val); |
| 1531 @end group | |
| 1532 @end example | |
| 1533 | |
| 1534 A difference between the oct-file interface to structures and the | |
| 1535 mex-file version is that the functions to operate on structures in | |
| 1536 mex-files directly include an @code{index} over the elements of the | |
| 1537 arrays of elements per @code{field}. Whereas the oct-file structure | |
| 1538 includes a Cell Array per field of the structure. | |
| 1539 | |
| 1540 An example that demonstrates the use of structures in mex-file can be | |
| 1541 found in the file @file{mystruct.c}, as seen below | |
| 6580 | 1542 |
| 9906 | 1543 @example |
| 1544 @EXAMPLEFILE(mystruct.c) | |
| 1545 @end example | |
| 6580 | 1546 |
| 6593 | 1547 An example of the behavior of this function within Octave is then |
| 1548 | |
| 1549 @example | |
| 7081 | 1550 a(1).f1 = "f11"; a(1).f2 = "f12"; |
| 1551 a(2).f1 = "f21"; a(2).f2 = "f22"; | |
| 6593 | 1552 b = mystruct(a) |
| 1553 @result{} field f1(0) = f11 | |
| 1554 field f1(1) = f21 | |
| 1555 field f2(0) = f12 | |
| 1556 field f2(1) = f22 | |
| 1557 b = | |
| 1558 @{ | |
| 1559 this = | |
| 1560 | |
| 1561 (, | |
| 1562 [1] = this1 | |
| 1563 [2] = this2 | |
| 1564 [3] = this3 | |
| 1565 [4] = this4 | |
| 1566 ,) | |
| 1567 | |
| 1568 that = | |
| 1569 | |
| 1570 (, | |
| 1571 [1] = that1 | |
| 1572 [2] = that2 | |
| 1573 [3] = that3 | |
| 1574 [4] = that4 | |
| 1575 ,) | |
| 1576 | |
| 1577 @} | |
| 1578 @end example | |
| 6569 | 1579 |
| 1580 @node Sparse Matrices with Mex-Files | |
| 1581 @subsection Sparse Matrices with Mex-Files | |
| 1582 | |
| 6593 | 1583 The Octave format for sparse matrices is identical to the mex format in |
| 7001 | 1584 that it is a compressed column sparse format. Also in both, sparse |
|
9209
923c7cb7f13f
Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction.
Rik <rdrider0-list@yahoo.com>
parents:
9080
diff
changeset
|
1585 matrices are required to be two-dimensional. The only difference is that |
| 6939 | 1586 the real and imaginary parts of the matrix are stored separately. |
| 6593 | 1587 |
| 1588 The mex-file interface, as well as using @code{mxGetM}, @code{mxGetN}, | |
| 1589 @code{mxSetM}, @code{mxSetN}, @code{mxGetPr}, @code{mxGetPi}, | |
| 1590 @code{mxSetPr} and @code{mxSetPi}, the mex-file interface supplies the | |
| 1591 functions | |
| 1592 | |
| 1593 @example | |
| 1594 @group | |
| 6686 | 1595 mwIndex *mxGetIr (const mxArray *ptr); |
| 1596 mwIndex *mxGetJc (const mxArray *ptr); | |
| 1597 mwSize mxGetNzmax (const mxArray *ptr); | |
| 6593 | 1598 |
| 6686 | 1599 void mxSetIr (mxArray *ptr, mwIndex *ir); |
| 1600 void mxSetJc (mxArray *ptr, mwIndex *jc); | |
| 1601 void mxSetNzmax (mxArray *ptr, mwSize nzmax); | |
| 6593 | 1602 @end group |
| 1603 @end example | |
| 6580 | 1604 |
| 6593 | 1605 @noindent |
| 1606 @code{mxGetNzmax} gets the maximum number of elements that can be stored | |
| 1607 in the sparse matrix. This is not necessarily the number of non-zero | |
| 1608 elements in the sparse matrix. @code{mxGetJc} returns an array with one | |
| 1609 additional value than the number of columns in the sparse matrix. The | |
| 1610 difference between consecutive values of the array returned by | |
| 1611 @code{mxGetJc} define the number of non-zero elements in each column of | |
| 1612 the sparse matrix. Therefore | |
| 6580 | 1613 |
| 6593 | 1614 @example |
| 1615 @group | |
| 6686 | 1616 mwSize nz, n; |
| 1617 mwIndex *Jc; | |
| 6593 | 1618 mxArray *m; |
| 1619 @dots{} | |
| 1620 n = mxGetN (m); | |
| 1621 Jc = mxGetJc (m); | |
| 1622 nz = Jc[n]; | |
| 1623 @end group | |
| 1624 @end example | |
| 1625 | |
| 1626 @noindent | |
| 1627 returns the actual number of non-zero elements stored in the matrix in | |
| 1628 @code{nz}. As the arrays returned by @code{mxGetPr} and @code{mxGetPi} | |
| 1629 only contain the non-zero values of the matrix, we also need a pointer | |
| 1630 to the rows of the non-zero elements, and this is given by | |
| 1631 @code{mxGetIr}. A complete example of the use of sparse matrices in | |
| 1632 mex-files is given by the file @file{mysparse.c} as seen below | |
| 1633 | |
| 9906 | 1634 @example |
| 1635 @EXAMPLEFILE(mysparse.c) | |
| 1636 @end example | |
| 6569 | 1637 |
| 6580 | 1638 @node Calling Other Functions in Mex-Files |
| 1639 @subsection Calling Other Functions in Mex-Files | |
| 1640 | |
| 1641 It is also possible call other Octave functions from within a mex-file | |
| 6593 | 1642 using @code{mexCallMATLAB}. An example of the use of |
| 6580 | 1643 @code{mexCallMATLAB} can be see in the example below |
| 1644 | |
| 9906 | 1645 @example |
| 1646 @EXAMPLEFILE(myfeval.c) | |
| 1647 @end example | |
| 6580 | 1648 |
| 1649 If this code is in the file @file{myfeval.c}, and is compiled to | |
| 1650 @file{myfeval.mex}, then an example of its use is | |
| 6569 | 1651 |
| 6580 | 1652 @example |
| 1653 @group | |
| 1654 myfeval("sin", 1) | |
| 1655 a = myfeval("sin", 1) | |
| 1656 @result{} Hello, World! | |
| 1657 I have 2 inputs and 1 outputs | |
| 1658 I'm going to call the interpreter function sin | |
| 1659 a = 0.84147 | |
| 1660 @end group | |
| 1661 @end example | |
| 1662 | |
| 1663 Note that it is not possible to use function handles or inline functions | |
| 1664 within a mex-file. | |
| 1665 | |
| 6593 | 1666 @c @node Application Programming Interface for Mex-Files |
| 1667 @c @subsection Application Programming Interface for Mex-Files | |
| 1668 @c | |
| 1669 @c WRITE ME, refer to mex.h and mexproto.h | |
| 6569 | 1670 |
| 1671 @node Standalone Programs | |
| 1672 @section Standalone Programs | |
| 1673 | |
| 1674 The libraries Octave itself uses, can be utilized in standalone | |
|
11573
6f8ffe2c6f76
Grammarcheck txi files for 3.4 release.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
1675 applications. These applications then have access, for example, to the |
|
6f8ffe2c6f76
Grammarcheck txi files for 3.4 release.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
1676 array and matrix classes as well as to all the Octave algorithms. The |
|
11479
746609dd54fd
Remove Matlab euphemisms in docs and use @file macro for filenames
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
10846
diff
changeset
|
1677 following C++ program, uses class Matrix from @file{liboctave.a} or |
|
746609dd54fd
Remove Matlab euphemisms in docs and use @file macro for filenames
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
10846
diff
changeset
|
1678 @file{liboctave.so}. |
| 6569 | 1679 |
| 9906 | 1680 @example |
| 1681 @group | |
| 1682 @EXAMPLEFILE(standalone.cc) | |
| 1683 @end group | |
| 1684 @end example | |
| 6569 | 1685 |
| 6580 | 1686 @noindent |
| 6569 | 1687 mkoctfile can then be used to build a standalone application with a |
| 1688 command like | |
| 1689 | |
| 1690 @example | |
| 1691 @group | |
|
8097
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1692 $ mkoctfile --link-stand-alone standalone.cc -o standalone |
|
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1693 $ ./standalone |
| 6569 | 1694 Hello Octave world! |
| 1695 11 12 | |
| 1696 21 22 | |
| 1697 $ | |
| 1698 @end group | |
| 1699 @end example | |
| 1700 | |
| 1701 Note that the application @code{hello} will be dynamically linked | |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1702 against the octave libraries and any octave support libraries. The above |
|
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1703 allows the Octave math libraries to be used by an application. It does |
|
8097
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1704 not however allow the script files, oct-files or builtin functions of |
|
9080
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1705 Octave to be used by the application. To do that the Octave interpreter |
|
ec41eabf4499
Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents:
9038
diff
changeset
|
1706 needs to be initialized first. An example of how to do this can then be |
|
8097
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1707 seen in the code |
|
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1708 |
| 9906 | 1709 @example |
| 1710 @group | |
| 1711 @EXAMPLEFILE(embedded.cc) | |
| 1712 @end group | |
| 1713 @end example | |
|
8097
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1714 |
|
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1715 @noindent |
|
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1716 which is compiled and run as before as a standalone application with |
|
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1717 |
|
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1718 @example |
|
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1719 @group |
|
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1720 $ mkoctfile --link-stand-alone embedded.cc -o embedded |
|
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1721 $ ./embedded |
|
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1722 GCD of [10, 15] is 5 |
|
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1723 $ |
|
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1724 @end group |
|
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1725 @end example |
|
804c60f92fb1
Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents:
7354
diff
changeset
|
1726 |