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