Mercurial > octave-nkf

annotate doc/interpreter/external.txi @ 20595:c1a6c31ac29a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
eliminate more simple uses of error_state * ov-classdef.cc: Eliminate simple uses of error_state.
author John W. Eaton <jwe@octave.org>
date Tue, 06 Oct 2015 00:20:02 -0400
parents b70cc4bd8109
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
19731
4197fc428c7d maint: Update copyright notices for 2015.
John W. Eaton <jwe@octave.org>
parents: 19630
diff changeset
1 @c Copyright (C) 2007-2015 John W. Eaton and David Bateman
7018
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe]
jwe
parents: 7007
diff changeset
2 @c Copyright (C) 2007 Paul Thomas and Christoph Spiel
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe]
jwe
parents: 7007
diff changeset
3 @c
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe]
jwe
parents: 7007
diff changeset
4 @c This file is part of Octave.
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe]
jwe
parents: 7007
diff changeset
5 @c
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe]
jwe
parents: 7007
diff changeset
6 @c Octave is free software; you can redistribute it and/or modify it
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe]
jwe
parents: 7007
diff changeset
7 @c under the terms of the GNU General Public License as published by the
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe]
jwe
parents: 7007
diff changeset
8 @c Free Software Foundation; either version 3 of the License, or (at
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe]
jwe
parents: 7007
diff changeset
9 @c your option) any later version.
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
10 @c
7018
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe]
jwe
parents: 7007
diff changeset
11 @c Octave is distributed in the hope that it will be useful, but WITHOUT
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe]
jwe
parents: 7007
diff changeset
12 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe]
jwe
parents: 7007
diff changeset
13 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe]
jwe
parents: 7007
diff changeset
14 @c for more details.
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
15 @c
7018
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe]
jwe
parents: 7007
diff changeset
16 @c You should have received a copy of the GNU General Public License
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe]
jwe
parents: 7007
diff changeset
17 @c along with Octave; see the file COPYING. If not, see
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe]
jwe
parents: 7007
diff changeset
18 @c <http://www.gnu.org/licenses/>.
6578
fbc16fe0e86a [project @ 2007-04-25 16:04:59 by jwe]
jwe
parents: 6577
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
18987
bcbd309bf272 doc: Fix quote character at beginning of External Code Interfaces chapter.
Rik <rik@octave.org>
parents: 18831
diff changeset
26 "The sum of human wisdom is not contained in any one language"
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
27 ---Ezra Pound
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
54
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
55 @itemize @bullet
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
79 of being interpreted.
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
80
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
87 @end itemize
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
105
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
110 @end menu
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
111
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
112 @node Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
113 @section Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
114 @cindex oct-files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
115 @cindex mkoctfile
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
116 @cindex oct
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
117
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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::
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
132 @c * Application Programming Interface for Oct-Files::
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
133 @end menu
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
134
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
135 @node Getting Started with Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
136 @subsection Getting Started with Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
146
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
147 @DOCSTRING(mkoctfile)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
151
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
152 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
153 @group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
154 @EXAMPLEFILE(helloworld.cc)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
155 @end group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
156 @end example
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
157
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
158 The first critical line is @code{#include <octave/oct.h>} which
16867
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
166
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
167 @enumerate 1
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
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
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
172 @item The number of output arguments, which can and often is omitted if
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
176 @end enumerate
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
179 @code{octave_value_list}.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
180
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
188 compiled to an oct-file using the command
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
189
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
190 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
191 mkoctfile helloworld.cc
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
192 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
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
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
204
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
205 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
206 @group
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
207 helloworld (1, 2, 3)
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
208 @print{} Hello World has 3 input arguments and 0 output arguments.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
209 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
210 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
219 @node Matrices and Arrays in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
220 @subsection Matrices and Arrays in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
221
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
222 Octave supports a number of different array and matrix classes, the
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
223 majority of which are based on the Array class. The exception is the
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
224 sparse matrix types discussed separately below. There are three basic
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
225 matrix types
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
226
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
227 @table @code
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
236 @end table
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
240
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
241 @table @code
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
242 @item NDArray
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
245 @item ComplexNDarray
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
248 @item boolNDArray
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
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
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
252 @itemx int16NDArray
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
253 @itemx int32NDArray
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
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
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
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
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
259 @itemx uint16NDArray
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
260 @itemx uint32NDArray
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
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
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
263 @file{uint8NDArray.h}, @file{uint16NDArray.h}, etc.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
264 @end table
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
269
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
270 @itemize @bullet
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
273
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
274 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
275 Matrix a;
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
276 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
283
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
284 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
285 @group
20222
998881b6cdef external.txi: Fix example case for dim_vector (bug #45100).
Piotr Held <pjheld@gmail.com>
parents: 19755
diff changeset
286 dim_vector dv (2, 3); // 2 rows, 3 columns
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
287 Matrix a (dv);
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
288 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
289 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
290
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
291 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
292
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
293 @item
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
294 Define the number of rows and columns in the matrix. For example:
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
295
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
296 @example
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
297 Matrix a (2, 2)
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
298 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
299
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
300 However, this constructor can only be used with matrix types.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
301 @end itemize
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
302
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
303 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
304 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
305 useful methods include
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
306
17281
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents: 17152
diff changeset
307 @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
308 @deftypefnx {Method} {T&} elem (octave_idx_type)
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
309 The @code{()} operator or @code{elem} method allow the values of the
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
310 matrix or array to be read or set. These can take a single argument,
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
311 which is of type @code{octave_idx_type}, that is the index into the matrix or
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
312 array. Additionally, the matrix type allows two argument versions of the
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
313 @code{()} operator and elem method, giving the row and column index of the
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
314 value to obtain or set.
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
315 @end deftypefn
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
316
7001
8b0cfeb06365 [project @ 2007-10-10 18:02:59 by jwe]
jwe
parents: 6939
diff changeset
317 Note that these functions do significant error checking and so in some
8b0cfeb06365 [project @ 2007-10-10 18:02:59 by jwe]
jwe
parents: 6939
diff changeset
318 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
319 matrix directly through the @nospell{fortran_vec} method discussed below.
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
320
17281
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents: 17152
diff changeset
321 @deftypefn {Method} {} octave_idx_type numel (void) const
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
322 The total number of elements in the matrix or array.
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
323 @end deftypefn
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
324
17281
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents: 17152
diff changeset
325 @deftypefn {Method} {size_t} byte_size (void) const
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
326 The number of bytes used to store the matrix or array.
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
327 @end deftypefn
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
328
17281
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents: 17152
diff changeset
329 @deftypefn {Method} {dim_vector} dims (void) const
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
330 The dimensions of the matrix or array in value of type dim_vector.
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
331 @end deftypefn
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
332
17281
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents: 17152
diff changeset
333 @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
334 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
335 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
336 @end deftypefn
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
337
17281
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents: 17152
diff changeset
338 @deftypefn {Method} {void} resize (const dim_vector&)
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
339 A method taking either an argument of type @code{dim_vector}, or in the
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
340 case of a matrix two arguments of type @code{octave_idx_type} defining
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
341 the number of rows and columns in the matrix.
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
342 @end deftypefn
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
343
17281
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents: 17152
diff changeset
344 @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
345 This method returns a pointer to the underlying data of the matrix or
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
346 array so that it can be manipulated directly, either within Octave or by
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
347 an external library.
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
348 @end deftypefn
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
349
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
350 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
351 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
352 methods that are of interest only for matrices such as @code{transpose},
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
353 @code{hermitian}, @code{solve}, etc.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
354
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
355 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
356 @w{@code{DEFUN_DLD}} function is as follows
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
357
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
358 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
359 @EXAMPLEFILE(addtwomatrices.cc)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
360 @end example
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
361
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
362 To avoid segmentation faults causing Octave to abort this function
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
363 explicitly checks that there are sufficient arguments available before
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
364 accessing these arguments. It then obtains two multi-dimensional arrays
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
365 of type @code{NDArray} and adds these together. Note that the array_value
20569
b70cc4bd8109 begin removal of global error_state variable
John W. Eaton <jwe@octave.org>
parents: 20222
diff changeset
366 method is called without using the @code{is_matrix_type} type. If an
b70cc4bd8109 begin removal of global error_state variable
John W. Eaton <jwe@octave.org>
parents: 20222
diff changeset
367 error occurs when attempting to extract the value, Octave will print a
b70cc4bd8109 begin removal of global error_state variable
John W. Eaton <jwe@octave.org>
parents: 20222
diff changeset
368 message and throw an exception. The reason to
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
369 prefer this is that the arguments might be a type that is not an
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
370 @code{NDArray}, but it would make sense to convert it to one. The
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
371 @code{array_value} method allows this conversion to be performed
20569
b70cc4bd8109 begin removal of global error_state variable
John W. Eaton <jwe@octave.org>
parents: 20222
diff changeset
372 transparently if possible. If you need to catch errors like this and
b70cc4bd8109 begin removal of global error_state variable
John W. Eaton <jwe@octave.org>
parents: 20222
diff changeset
373 perform some kind of cleanup or other operation, you can catch the
b70cc4bd8109 begin removal of global error_state variable
John W. Eaton <jwe@octave.org>
parents: 20222
diff changeset
374 @code{octave_execution_error} exception.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
375
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
376 @code{A + B}, operating on two @code{NDArray}'s returns an
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
379
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
380 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
385 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
386 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
387
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
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
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
390 listed below.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
391
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
394 @item @code{RowVector} @tab @code{row_vector_value} @tab @file{dRowVector.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
395 @item @code{ComplexRowVector} @tab @code{complex_row_vector_value} @tab @file{CRowVector.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
396 @item @code{ColumnVector} @tab @code{column_vector_value} @tab @file{dColVector.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
397 @item @code{ComplexColumnVector} @tab @code{complex_column_vector_value} @tab @file{CColVector.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
398 @item @code{Matrix} @tab @code{matrix_value} @tab @file{dMatrix.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
399 @item @code{ComplexMatrix} @tab @code{complex_matrix_value} @tab @file{CMatrix.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
400 @item @code{boolMatrix} @tab @code{bool_matrix_value} @tab @file{boolMatrix.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
401 @item @code{charMatrix} @tab @code{char_matrix_value} @tab @file{chMatrix.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
402 @item @code{NDArray} @tab @code{array_value} @tab @file{dNDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
403 @item @code{ComplexNDArray} @tab @code{complex_array_value} @tab @file{CNDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
404 @item @code{boolNDArray} @tab @code{bool_array_value} @tab @file{boolNDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
405 @item @code{charNDArray} @tab @code{char_array_value} @tab @file{charNDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
406 @item @code{int8NDArray} @tab @code{int8_array_value} @tab @file{int8NDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
407 @item @code{int16NDArray} @tab @code{int16_array_value} @tab @file{int16NDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
408 @item @code{int32NDArray} @tab @code{int32_array_value} @tab @file{int32NDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
409 @item @code{int64NDArray} @tab @code{int64_array_value} @tab @file{int64NDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
410 @item @code{uint8NDArray} @tab @code{uint8_array_value} @tab @file{uint8NDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
411 @item @code{uint16NDArray} @tab @code{uint16_array_value} @tab @file{uint16NDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
412 @item @code{uint32NDArray} @tab @code{uint32_array_value} @tab @file{uint32NDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
413 @item @code{uint64NDArray} @tab @code{uint64_array_value} @tab @file{uint64NDArray.h}
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
414 @end multitable
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
415
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
416 @node Character Strings in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
417 @subsection Character Strings in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
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
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
421
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
422 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
423 @EXAMPLEFILE(stringdemo.cc)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
424 @end example
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
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
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
427
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
428 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
429 @group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
430 s0 = ["First String"; "Second String"];
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
431 [s1,s2] = stringdemo (s0)
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
432 @result{} s1 = Second String
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
433 First String
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
434
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
435 @result{} s2 = First String
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
436 Second String
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
437
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
438 typeinfo (s2)
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
439 @result{} sq_string
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
440 typeinfo (s1)
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
441 @result{} string
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
442 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
443 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
444
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
445 One additional complication of strings in Octave is the difference
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
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
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
449
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
450 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
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
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
456 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
457 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
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
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
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
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
462
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
463 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
464 @group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
465 octave_value_list retval;
18358
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
466 charNDArray ch;
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
467 @dots{}
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
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
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
472
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
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
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
475 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
476 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
477
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
478 @node Cell Arrays in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
479 @subsection Cell Arrays in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
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
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
484 example is
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
485
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
486 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
487 @EXAMPLEFILE(celldemo.cc)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
488 @end example
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
489
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
490 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
491 the @file{Cell.h} header file must be explicitly included. The rest of the
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
492 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
493 returns them as individual return arguments. For example:
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
494
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
495 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
496 @group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
497 [b1, b2, b3] = celldemo (@{1, [1, 2], "test"@})
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
498 @result{}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
499 b1 = 1
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
500 b2 =
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
501
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
502 1 2
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
503
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
504 b3 = test
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
505 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
506 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
507
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
508 @node Structures in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
509 @subsection Structures in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
510
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
511 A structure in Octave is a map between a number of fields represented and
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
512 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
513 with the pair consisting of a @code{std::string} and an Octave
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
514 @code{Cell} variable.
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
515
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
516 A simple example demonstrating the use of structures within oct-files is
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
517
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
518 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
519 @EXAMPLEFILE(structdemo.cc)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
520 @end example
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
521
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
522 An example of its use is
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
523
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
524 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
525 @group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
526 x.a = 1; x.b = "test"; x.c = [1, 2];
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
527 structdemo (x, "b")
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
528 @result{} selected = test
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
529 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
530 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
531
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
532 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
533 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
534 @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
535 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
536 @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
537 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
538 this single-struct example we write
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
539
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
540 @example
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
541 octave_value tmp = arg0.contents (arg1)(0);
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
542 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
543
10846
a4f482e66b65 Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents: 10828
diff changeset
544 @noindent
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
545 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
546 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
547 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
548
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
549 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
550 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
551 than relying on just @code{contents}.
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
552
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
553 @node Sparse Matrices in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
554 @subsection Sparse Matrices in Oct-Files
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
555
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
556 There are three classes of sparse objects that are of interest to the user.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
557
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
558 @table @code
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
559 @item SparseMatrix
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
560 A double precision sparse matrix class
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
561
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
562 @item SparseComplexMatrix
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
563 A complex sparse matrix class
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
564
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
565 @item SparseBoolMatrix
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
566 A boolean sparse matrix class
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
567 @end table
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
568
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
569 All of these classes inherit from the @code{Sparse<T>} template class,
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
570 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
571 class was based on Octave's @code{Array<T>} class, and so users familiar
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
572 with Octave's @code{Array} classes will be comfortable with the use of
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
573 the sparse classes.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
574
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
575 The sparse classes will not be entirely described in this section, due
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
576 to their similarity with the existing @code{Array} classes. However,
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
577 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
578 and these will be described. First, although it is fundamentally
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
579 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
580 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
581 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
582 more similar to Octave's @code{Matrix} class than its @code{NDArray} class.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
583
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
584 @menu
17152
f2a8592b8fbd doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents: 17097
diff changeset
585 * Array and Sparse Class Differences::
f2a8592b8fbd doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents: 17097
diff changeset
586 * Creating Sparse Matrices in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents: 17097
diff changeset
587 * Using Sparse Matrices in Oct-Files::
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
588 @end menu
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
589
17152
f2a8592b8fbd doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents: 17097
diff changeset
590 @node Array and Sparse Class Differences
f2a8592b8fbd doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents: 17097
diff changeset
591 @subsubsection Array and Sparse Class Differences
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
592
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
593 The number of elements in a sparse matrix is considered to be the number
18851
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18831
diff changeset
594 of nonzero elements rather than the product of the dimensions. Therefore
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
595
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
596 @example
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
597 @group
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
598 SparseMatrix sm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
599 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
600 int nel = sm.nelem ();
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
601 @end group
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
602 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
603
10846
a4f482e66b65 Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents: 10828
diff changeset
604 @noindent
18851
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18831
diff changeset
605 returns the number of nonzero elements. If the user really requires the
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18831
diff changeset
606 number of elements in the matrix, including the nonzero elements, they
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
607 should use @code{numel} rather than @code{nelem}. Note that for very
7001
8b0cfeb06365 [project @ 2007-10-10 18:02:59 by jwe]
jwe
parents: 6939
diff changeset
608 large matrices, where the product of the two dimensions is larger than
8b0cfeb06365 [project @ 2007-10-10 18:02:59 by jwe]
jwe
parents: 6939
diff changeset
609 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
610 An example is @code{speye (1e6)} which will create a matrix with a million
18851
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18831
diff changeset
611 rows and columns, but only a million nonzero elements. Therefore the
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
612 number of rows by the number of columns in this case is more than two
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
613 hundred times the maximum value that can be represented by an unsigned int.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
614 The use of @code{numel} should therefore be avoided useless it is known
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
615 it won't overflow.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
616
17281
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents: 17152
diff changeset
617 Extreme care must be take with the elem method and the @qcode{"()"} operator,
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
618 which perform basically the same function. The reason is that if a
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
619 sparse object is non-const, then Octave will assume that a
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
620 request for a zero element in a sparse matrix is in fact a request
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
621 to create this element so it can be filled. Therefore a piece of
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
622 code like
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
623
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
624 @example
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
625 @group
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
626 SparseMatrix sm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
627 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
628 for (int j = 0; j < nc; j++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
629 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
630 std::cerr << " (" << i << "," << j << "): " << sm(i,j) << std::endl;
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
631 @end group
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
632 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
633
10846
a4f482e66b65 Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents: 10828
diff changeset
634 @noindent
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
635 is a great way of turning the sparse matrix into a dense one, and a
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
636 very slow way at that since it reallocates the sparse object at each
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
637 zero element in the matrix.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
638
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
639 An easy way of preventing the above from happening is to create a temporary
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
640 constant version of the sparse matrix. Note that only the container for
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
641 the sparse matrix will be copied, while the actual representation of the
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
642 data will be shared between the two versions of the sparse matrix. So this
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
643 is not a costly operation. For example, the above would become
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
644
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
645 @example
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
646 @group
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
647 SparseMatrix sm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
648 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
649 const SparseMatrix tmp (sm);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
650 for (int j = 0; j < nc; j++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
651 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
652 std::cerr << " (" << i << "," << j << "): " << tmp(i,j) << std::endl;
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
653 @end group
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
654 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
655
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
656 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
657 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
658 is not available. It is, however, replaced by three separate methods
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
659 @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
660 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
661 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
662 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
663 matrix compressed column format.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
664
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
665 @node Creating Sparse Matrices in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
666 @subsubsection Creating Sparse Matrices in Oct-Files
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
667
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
668 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
669 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
670 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
671 The second alternative is to create a sparse matrix with the appropriate
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
672 amount of space and then fill in the values. Both techniques have their
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
673 advantages and disadvantages.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
674
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
675 Below is an example of creating a small sparse matrix using the first
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
676 technique
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
677
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
678 @example
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
679 @group
18358
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
680 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
681 nz = 4, nr = 3, nc = 4;
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
682
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
683 ColumnVector ridx (nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
684 ColumnVector cidx (nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
685 ColumnVector data (nz);
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
686
18831
96f22d6674c4 Fix incorrect sparse matrix example code in oct-file chapter (bug #41799).
Rik <rik@octave.org>
parents: 18830
diff changeset
687 ridx(0) = 1; cidx(0) = 1; data(0) = 1;
96f22d6674c4 Fix incorrect sparse matrix example code in oct-file chapter (bug #41799).
Rik <rik@octave.org>
parents: 18830
diff changeset
688 ridx(1) = 2; cidx(1) = 2; data(1) = 2;
96f22d6674c4 Fix incorrect sparse matrix example code in oct-file chapter (bug #41799).
Rik <rik@octave.org>
parents: 18830
diff changeset
689 ridx(2) = 2; cidx(2) = 4; data(2) = 3;
96f22d6674c4 Fix incorrect sparse matrix example code in oct-file chapter (bug #41799).
Rik <rik@octave.org>
parents: 18830
diff changeset
690 ridx(3) = 3; cidx(3) = 4; data(3) = 4;
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
691 SparseMatrix sm (data, ridx, cidx, nr, nc);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
692 @end group
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
693 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
694
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
695 @noindent
8817
03b7f618ab3d include docstrings for new functions in the manual
John W. Eaton <jwe@octave.org>
parents: 8486
diff changeset
696 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
697 @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
698 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
699 but is used internally.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
700
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
701 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
702 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
703 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
704 data will significantly speed up creation of the sparse matrix.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
705
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
706 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
707 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
708 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
709 technique for creating a sparse matrix.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
710
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
711 The alternative is to first create a sparse matrix with the desired
18851
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18831
diff changeset
712 number of nonzero elements and then later fill those elements in.
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
713 Sample code:
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
714
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
715 @example
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
716 @group
18358
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
717 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
718 nz = 4, nr = 3, nc = 4;
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
719 SparseMatrix sm (nr, nc, nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
720 sm(0,0) = 1; sm(0,1) = 2; sm(1,3) = 3; sm(2,3) = 4;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
721 @end group
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
722 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
734
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
735 @example
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
736 @group
18358
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
737 int nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
738 nr = 3, nc = 4;
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
739 SparseMatrix sm (nr, nc, 0);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
740 sm(0,0) = 1; sm(0,1) = 2; sm(1,3) = 3; sm(2,3) = 4;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
741 @end group
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
742 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
743
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
744 @noindent
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
745 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
746 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
747 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
748 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
749 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
750 @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
751 occupies more memory than strictly needed.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
752
18851
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18831
diff changeset
753 It is not always possible to know the number of nonzero elements prior
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
754 to filling a matrix. For this reason the additional unused storage of
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
755 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
756 @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
757 deallocate the unused storage, but it can also remove zero elements
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
758 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
759 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
760 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
761 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
762 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
763 An example of the use of @code{maybe_compress} is
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
764
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
765 @example
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
766 @group
18358
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
767 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
768 nz = 6, nr = 3, nc = 4;
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
769
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
770 SparseMatrix sm1 (nr, nc, nz);
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
771 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
772 sm1.maybe_compress (); // No zero elements were added
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
773
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
774 SparseMatrix sm2 (nr, nc, nz);
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
775 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
776 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
777 sm2.maybe_compress (true); // Zero elements were added
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
778 @end group
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
779 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
780
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
781 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
782 possible as it will slow the creation of the matrix.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
783
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
784 A third means of creating a sparse matrix is to work directly with
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
785 the data in compressed row format. An example of this technique might
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
786 be
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
787
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
788 @example
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
789 octave_value arg;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
790 @dots{}
18358
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
791 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
792 nz = 6, nr = 3, nc = 4; // Assume we know the max # nz
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
793 SparseMatrix sm (nr, nc, nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
794 Matrix m = arg.matrix_value ();
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
795
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
796 int ii = 0;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
797 sm.cidx (0) = 0;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
798 for (int j = 1; j < nc; j++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
799 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
800 for (int i = 0; i < nr; i++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
801 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
802 double tmp = foo (m(i,j));
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
803 if (tmp != 0.)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
804 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
805 sm.data(ii) = tmp;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
806 sm.ridx(ii) = i;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
807 ii++;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
808 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
809 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
810 sm.cidx(j+1) = ii;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
811 @}
18830
322eb69e30ad doc: Fix some Latin wording in documentation.
Rik <rik@octave.org>
parents: 18534
diff changeset
812 sm.maybe_compress (); // If don't know a priori the final # of nz.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
813 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
814
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
815 @noindent
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
816 which is probably the most efficient means of creating a sparse matrix.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
817
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
818 Finally, it might sometimes arise that the amount of storage initially
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
819 created is insufficient to completely store the sparse matrix. Therefore,
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
820 the method @code{change_capacity} exists to reallocate the sparse memory.
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
821 The above example would then be modified as
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
822
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
823 @example
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
824 octave_value arg;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
825 @dots{}
18358
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
826 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
827 nz = 6, nr = 3, nc = 4; // Assume we know the max # nz
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
828 SparseMatrix sm (nr, nc, nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
829 Matrix m = arg.matrix_value ();
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
830
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
831 int ii = 0;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
832 sm.cidx (0) = 0;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
833 for (int j = 1; j < nc; j++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
834 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
835 for (int i = 0; i < nr; i++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
836 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
837 double tmp = foo (m(i,j));
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
838 if (tmp != 0.)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
839 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
840 if (ii == nz)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
841 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
842 nz += 2; // Add 2 more elements
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
843 sm.change_capacity (nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
844 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
845 sm.data(ii) = tmp;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
846 sm.ridx(ii) = i;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
847 ii++;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
848 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
849 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
850 sm.cidx(j+1) = ii;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
851 @}
18830
322eb69e30ad doc: Fix some Latin wording in documentation.
Rik <rik@octave.org>
parents: 18534
diff changeset
852 sm.maybe_mutate (); // If don't know a priori the final # of nz.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
853 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
854
18851
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18831
diff changeset
855 Note that both increasing and decreasing the number of nonzero elements in
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
856 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
857 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
858 at the same time, additional memory is needed. Therefore, if possible this
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
859 should be avoided.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
860
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
861 @node Using Sparse Matrices in Oct-Files
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
862 @subsubsection Using Sparse Matrices in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
863
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
864 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
865 available from the Octave command line are also available within oct-files.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
866 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
867 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
868 following example.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
869
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
870 @example
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
871 @group
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
872 octave_value_list retval;
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
873
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
874 SparseMatrix sm = args(0).sparse_matrix_value ();
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
875 SparseComplexMatrix scm =
7081
503001863427 [project @ 2007-10-31 01:08:14 by jwe]
jwe
parents: 7018
diff changeset
876 args(1).sparse_complex_matrix_value ();
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
877 SparseBoolMatrix sbm = args(2).sparse_bool_matrix_value ();
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
878 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
879 retval(2) = sbm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
880 retval(1) = scm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
881 retval(0) = sm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
882 @end group
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
883 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
884
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
885 The conversion to an @code{octave_value} is handled by the sparse
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
886 @code{octave_value} constructors, and so no special care is needed.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
887
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
888 @node Accessing Global Variables in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
889 @subsection Accessing Global Variables in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
890
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
891 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
892 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
893 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
894 @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
895 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
896 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
897 An example of the use of these two functions is
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
898
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
899 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
900 @EXAMPLEFILE(globaldemo.cc)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
901 @end example
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
902
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
903 An example of its use is
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
904
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
905 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
906 @group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
907 global a b
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
908 b = 10;
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
909 globaldemo ("b")
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
910 @result{} 10
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
911 globaldemo ("c")
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
912 @result{} "Global variable not found"
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
913 num2str (a)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
914 @result{} 42
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
915 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
916 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
917
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
918 @node Calling Octave Functions from Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
919 @subsection Calling Octave Functions from Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
920
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
921 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
922 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
923 itself. For example, the @code{quad} function is an oct-file that
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
924 calculates the definite integral by quadrature over a user supplied
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
925 function.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
926
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
927 There are also many ways in which a function might be passed. It might
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
928 be passed as one of
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
929
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
930 @enumerate 1
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
931 @item Function Handle
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
932
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
933 @item Anonymous Function Handle
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
934
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
935 @item Inline Function
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
936
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
937 @item String
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
938 @end enumerate
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
939
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
940 The example below demonstrates an example that accepts all four means of
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
941 passing a function to an oct-file.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
942
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
943 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
944 @EXAMPLEFILE(funcdemo.cc)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
945 @end example
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
946
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
947 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
948 and the remaining arguments are all passed to the user function.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
949
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
950 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
951 @group
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
952 funcdemo (@@sin,1)
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
953 @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
954 funcdemo (@@(x) sin (x), 1)
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
955 @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
956 funcdemo (inline ("sin (x)"), 1)
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
957 @result{} 0.84147
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
958 funcdemo ("sin",1)
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
959 @result{} 0.84147
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
960 funcdemo (@@atan2, 1, 1)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
961 @result{} 0.78540
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
962 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
963 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
964
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
965 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
966 function is different. In some cases it is necessary to have the
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
967 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
968 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
969 as demonstrated below.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
970
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
971 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
972 @group
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
973 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
974 std::string fcode = "function y = ";
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
975 fcode.append (fcn_name);
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
976 fcode.append ("(x) y = ");
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
977 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
978 fcode, "; endfunction");
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
979 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
980 if (fcn_name.length ())
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
981 clear_function (fcn_name);
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
982 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
983 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
984
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
985 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
986 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
987 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
988 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
989 internal function names begin and end with the character sequence @samp{__}.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
990
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
991 @node Calling External Code from Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
992 @subsection Calling External Code from Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
993
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
994 Linking external C code to Octave is relatively simple, as the C
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
995 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
996 that the declarations of the external C functions may need to be explicitly
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
997 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
998 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
999 ensure that the C++ compiler treats these declarations as C code is
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1000
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1001 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1002 @group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1003 #ifdef __cplusplus
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
1004 extern "C"
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1005 @{
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1006 #endif
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1007 #include "foo.h"
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1008 #ifdef __cplusplus
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1009 @} /* end extern "C" */
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1010 #endif
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1011 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1012 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1013
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1014 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
1015 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
1016 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
1017 behavior across a number of compilers.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1018
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1019 The underlying Fortran code should use the @code{XSTOPX} function to
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
1020 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
1021 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
1022 explicitly. Note that Octave supplies its own replacement @sc{blas}
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1023 @code{XERBLA} function, which uses @code{XSTOPX}.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1024
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1025 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
1026 macro should be used to call the underlying Fortran function. The Fortran
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1027 exception state can then be checked with the global variable
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
1028 @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
1029 then the @w{@code{F77_FCN}} macro should be used instead to call the Fortran
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1030 code.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1031
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1032 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
1033 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
1034 there is potentially an overhead in doing so. However, if @w{@code{F77_FCN}}
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1035 is used with code that calls @code{XSTOP}, Octave can generate a
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1036 segmentation fault.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1037
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1038 An example of the inclusion of a Fortran function in an oct-file is
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1039 given in the following example, where the C++ wrapper is
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1040
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1041 @example
18369
4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix.
Rik <rik@octave.org>
parents: 18367
diff changeset
1042 @EXAMPLEFILE(fortrandemo.cc)
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1043 @end example
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1044
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
1045 @noindent
10791
3140cb7a05a1 Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents: 9906
diff changeset
1046 and the Fortran function is
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1047
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1048 @example
18369
4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix.
Rik <rik@octave.org>
parents: 18367
diff changeset
1049 @EXAMPLEFILE(fortransub.f)
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1050 @end example
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1051
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1052 This example demonstrates most of the features needed to link to an
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1053 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
1054 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
1055 in order for the example to work.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1056
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1057 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1058 @group
18369
4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix.
Rik <rik@octave.org>
parents: 18367
diff changeset
1059 mkoctfile fortrandemo.cc fortransub.f
4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix.
Rik <rik@octave.org>
parents: 18367
diff changeset
1060 [b, s] = fortrandemo (1:3)
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1061 @result{}
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1062 b = 1.00000 0.50000 0.33333
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1063 s = There are 3 values in the input vector
18369
4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix.
Rik <rik@octave.org>
parents: 18367
diff changeset
1064 [b, s] = fortrandemo (0:3)
4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix.
Rik <rik@octave.org>
parents: 18367
diff changeset
1065 error: fortrandemo: fortransub: divide by zero
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1066 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1067 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1068
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1069 @node Allocating Local Memory in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1070 @subsection Allocating Local Memory in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1071
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1072 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
1073 new/delete operators can be used. However, in that case great care must be
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
1074 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
1075 memory for use locally is to use the @w{@code{OCTAVE_LOCAL_BUFFER}} macro.
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
1076 An example of its use is
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1077
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1078 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1079 OCTAVE_LOCAL_BUFFER (double, tmp, len)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1080 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1081
10846
a4f482e66b65 Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents: 10828
diff changeset
1082 @noindent
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1083 that returns a pointer @code{tmp} of type @code{double *} of length
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1084 @code{len}.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1085
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1086 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
1087 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
1088
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1089 @node Input Parameter Checking in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1090 @subsection Input Parameter Checking in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1091
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1092 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
1093 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
1094 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
1095 of parameter checking to ensure that Octave behaves well.
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1096
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1097 The minimum requirement, as previously discussed, is to check the number
19755
bf6a909d3d11 doc: Use 'nonexistent' rather than 'non-existent' in documentation.
Rik <rik@octave.org>
parents: 19731
diff changeset
1098 of input arguments before using them to avoid referencing a nonexistent
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1099 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
1100 underlying code imposes further constraints. For example, an external
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1101 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
1102 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
1103 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
1104 input parameter checking.
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1105
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1106 There are several functions within Octave that can be useful for the
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1107 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
1108 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
1109 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
1110 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
1111 specialized input validation functions of which a few are demonstrated below.
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1112
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1113 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1114 @EXAMPLEFILE(paramdemo.cc)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1115 @end example
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1116
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1117 @noindent
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
1118 An example of its use is:
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1119
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1120 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1121 @group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1122 paramdemo ([1, 2, NaN, Inf])
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1123 @result{} Properties of input array:
18358
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1124 includes Inf or NaN values
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1125 includes other values than 1 and 0
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1126 includes only int, Inf or NaN values
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1127 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1128 @end example
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1129
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1130 @node Exception and Error Handling in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1131 @subsection Exception and Error Handling in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1132
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1133 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
1134 typing @key{Control-C} even during calculations. This ability is based on the
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1135 C++ exception handler, where memory allocated by the C++ new/delete
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
1136 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
1137 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
1138 the @w{@code{OCTAVE_QUIT}} macro is supplied. For example:
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1139
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1140 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1141 @group
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
1142 for (octave_idx_type i = 0; i < a.nelem (); i++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
1143 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
1144 OCTAVE_QUIT;
14856
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents: 14846
diff changeset
1145 b.elem (i) = 2. * a.elem (i);
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
1146 @}
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1147 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1148 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1149
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
1150 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
1151 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
1152 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
1153 processed, or press @key{Control-C} three times to force Octave to exit.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1154
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
1155 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
1156 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
1157 @w{@code{OCTAVE_QUIT}}.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1158
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1159 When creating an oct-file that uses an external libraries, the function
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1160 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
1161 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
1162 in this case. The alternative in this case is
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1163
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1164 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1165 @group
6577
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
1166 BEGIN_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
1167 @dots{} some code that calls a "foreign" function @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe]
jwe
parents: 6572
diff changeset
1168 END_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE;
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1169 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1170 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1171
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1172 The disadvantage of this is that if the foreign code allocates any
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1173 memory internally, then this memory might be lost during an interrupt,
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
1174 without being deallocated. Therefore, ideally Octave itself should
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1175 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
1176 @nospell{fortran_vec} method or the @w{@code{OCTAVE_LOCAL_BUFFER}} macro.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1177
15684
ddc651eecf7a Fix Info index for language statements (bug #37787)
Rik <rik@octave.org>
parents: 14138
diff changeset
1178 The Octave unwind_protect mechanism (@ref{The unwind_protect Statement})
6571
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe]
jwe
parents: 6569
diff changeset
1179 can also be used in oct-files. In conjunction with the exception
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1180 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
1181 to allow variables, etc.@: to be restored even if an exception occurs. An
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1182 example of the use of this mechanism is
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1183
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1184 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1185 @EXAMPLEFILE(unwinddemo.cc)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1186 @end example
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1187
10828
322f43e0e170 Grammarcheck .txi documentation files.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
1188 As can be seen in the example:
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1189
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1190 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1191 @group
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
1192 unwinddemo (1, 0)
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1193 @result{} Inf
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1194 1 / 0
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1195 @result{} warning: division by zero
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1196 Inf
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1197 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1198 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1199
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1200 The warning for division by zero (and in fact all warnings) are disabled in the
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1201 @code{unwinddemo} function.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1202
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1203 @node Documentation and Test of Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1204 @subsection Documentation and Test of Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1205
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1206 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
1207 @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
1208 as the help strings for user functions (@pxref{Documentation Tips}),
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1209 however there are some issue that are particular to the formatting of
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1210 help strings within oct-files.
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1211
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1212 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
1213 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
1214 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
1215 common is illustrated in the following example,
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1216
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1217 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1218 @group
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1219 DEFUN_DLD (do_what_i_want, args, nargout,
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1220 "-*- texinfo -*-\n\
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1221 @@deftypefn @{Function File@} @{@} do_what_i_say (@@var@{n@})\n\
7081
503001863427 [project @ 2007-10-31 01:08:14 by jwe]
jwe
parents: 7018
diff changeset
1222 A function that does what the user actually wants rather\n\
503001863427 [project @ 2007-10-31 01:08:14 by jwe]
jwe
parents: 7018
diff changeset
1223 than what they requested.\n\
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1224 @@end deftypefn")
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1225 @{
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1226 @dots{}
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1227 @}
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1228 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1229 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1230
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1231 @noindent
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1232 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
1233 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
1234 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
1235 character on the line.
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1236
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1237 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
1238 code for a function within the code itself (@pxref{Test and Demo Functions}).
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1239 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
1240 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
1241 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
1242 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
1243 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
1244 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
1245 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
1246 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
1247 from the compiled code. An example in an oct-file might be
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1248
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1249 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1250 @group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1251 /*
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1252 %!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
1253 %!error (sin ())
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents: 14846
diff changeset
1254 %!error (sin (1,1))
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1255 */
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1256 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1257 @end example
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1258
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1259 @c @node Application Programming Interface for Oct-Files
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1260 @c @subsection Application Programming Interface for Oct-Files
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1261 @c
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1262 @c WRITE ME, using Coda section 1.3 as a starting point.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1263
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1264 @node Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1265 @section Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1266 @cindex mex-files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1267 @cindex mex
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1268
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1269 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
1270 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
1271 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
1272 @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
1273 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
1274 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
1275 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
1276 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
1277 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
1278 be written with the oct-file interface previously discussed.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1279
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1280 @menu
17152
f2a8592b8fbd doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents: 17097
diff changeset
1281 * Getting Started with Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents: 17097
diff changeset
1282 * 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
1283 * Character Strings in Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents: 17097
diff changeset
1284 * Cell Arrays with Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents: 17097
diff changeset
1285 * Structures with Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents: 17097
diff changeset
1286 * Sparse Matrices with Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual.
Rik <rik@octave.org>
parents: 17097
diff changeset
1287 * Calling Other Functions in Mex-Files::
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1288 @c * Application Programming Interface for Mex-Files::
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1289 @end menu
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1290
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1291 @node Getting Started with Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1292 @subsection Getting Started with Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1293
11479
746609dd54fd Remove Matlab euphemisms in docs and use @file macro for filenames
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents: 10846
diff changeset
1294 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
1295 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
1296 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
1297 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
1298 Compiled mex-files have the extension @file{.mex}.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1299
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1300 @DOCSTRING(mex)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1301
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1302 @DOCSTRING(mexext)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1303
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1304 Consider the following short example:
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1305
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1306 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1307 @group
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1308 @EXAMPLEFILE(myhello.c)
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1309 @end group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1310 @end example
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1311
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1312 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
1313 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
1314 @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
1315 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
1316 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
1317 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
1318
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1319 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
1320 function takes four arguments:
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1321
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1322 @enumerate 1
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1323 @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
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 return arguments.
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1326
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1327 @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
1328
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1329 @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
1330 @end enumerate
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1331
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1332 Note that the function name definition is not explicitly included in
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1333 @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
1334 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
1335 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
1336 if the above function is in the file @file{myhello.c}, it can be compiled with
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1337
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1338 @example
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1339 mkoctfile --mex myhello.c
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1340 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1341
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1342 @noindent
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1343 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
1344 Octave as
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1345
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1346 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1347 @group
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1348 myhello (1,2,3)
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1349 @result{} Hello, World!
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1350 @result{} I have 3 inputs and 0 outputs
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1351 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1352 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1353
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1354 It should be noted that the mex-file contains no help string for the
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1355 functions it contains. To document mex-files, there should exist an
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1356 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
1357 an example, we would therefore have a file @file{myhello.m} that might
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1358 contain the text
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1359
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1360 @example
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1361 %MYHELLO Simple test of the functionality of a mex-file.
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1362 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1363
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1364 In this case, the function that will be executed within Octave will be
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1365 given by the mex-file, while the help string will come from the
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1366 m-file. This can also be useful to allow a sample implementation of the
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1367 mex-file within the Octave language itself for testing purposes.
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1368
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1369 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
1370 one can use the @code{mexFunctionName} function to determine what name
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1371 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
1372 the mex-file based on the function name. For example, if
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1373
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1374 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1375 @group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1376 @EXAMPLEFILE(myfunc.c)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1377 @end group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1378 @end example
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1379
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1380 @noindent
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1381 is in file @file{myfunc.c}, and it is compiled with
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1382
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1383 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1384 @group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1385 mkoctfile --mex myfunc.c
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1386 ln -s myfunc.mex myfunc2.mex
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1387 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1388 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1389
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1390 @noindent
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1391 then as can be seen by
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1392
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1393 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1394 @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
1395 myfunc ()
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1396 @result{} You called function: myfunc
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1397 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
1398 myfunc2 ()
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1399 @result{} You called function: myfunc2
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1400 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1401 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1402
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1403 @noindent
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1404 the behavior of the mex-file can be altered depending on the functions
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1405 name.
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1406
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1407 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
1408 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
1409 write mex-files in the headers @file{mexproto.h} and @file{mxarray.h}.
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1410
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1411 @node Working with Matrices and Arrays in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1412 @subsection Working with Matrices and Arrays in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1413
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1414 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
1415 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
1416 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
1417 octave_value class in oct-files in that it acts as a container for the
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1418 more specialized types.
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1419
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1420 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
1421 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
1422 real or complex. It can also contain a number of additional fields
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1423 depending on the type of the @code{mxArray}. There are a number of
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1424 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
1425 @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
1426 and the generic @code{mxCreateNumericArray}.
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1427
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1428 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
1429 @code{mxGetPr}. As the mex interface assumes that real and imaginary
6939
46d1ad37d943 [project @ 2007-10-01 16:12:20 by jwe]
jwe
parents: 6686
diff changeset
1430 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
1431 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
1432 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
1433 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
1434 on all matrix types. For example:
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1435
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1436 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1437 @group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1438 mxArray *m;
6686
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman]
dbateman
parents: 6606
diff changeset
1439 mwSize *dims;
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1440 UINT32_T *pr;
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1441
14856
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents: 14846
diff changeset
1442 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
1443 dims[0] = 2; dims[1] = 2;
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1444 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
1445 pr = (UINT32_T *) mxGetData (m);
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1446 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1447 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1448
9080
ec41eabf4499 Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents: 9038
diff changeset
1449 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
1450 inverse, and set the data of an array to use the block of memory pointed
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1451 to by the argument of @code{mxSetPr}.
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1452
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1453 Note the type @code{mwSize} used above, and also @code{mwIndex}, are defined
6686
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman]
dbateman
parents: 6606
diff changeset
1454 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
1455 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
1456 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
1457 and the maximum number or elements, while @code{mwIndex} is used to define
6686
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman]
dbateman
parents: 6606
diff changeset
1458 indexing into arrays.
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman]
dbateman
parents: 6606
diff changeset
1459
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1460 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
1461 double precision arrays is given by the file @file{mypow2.c} shown below.
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1462
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1463 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1464 @EXAMPLEFILE(mypow2.c)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1465 @end example
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1466
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1467 @noindent
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1468 with an example of its use
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1469
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1470 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1471 @group
14856
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents: 14846
diff changeset
1472 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
1473 all (b.^2 == mypow2 (b))
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1474 @result{} 1
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1475 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1476 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1477
7096
81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe]
jwe
parents: 7081
diff changeset
1478 The example above uses the functions @code{mxGetDimensions},
81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe]
jwe
parents: 7081
diff changeset
1479 @code{mxGetNumberOfElements}, and @code{mxGetNumberOfDimensions} to work
81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe]
jwe
parents: 7081
diff changeset
1480 with the dimensions of multi-dimensional arrays. The functions
81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe]
jwe
parents: 7081
diff changeset
1481 @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
1482 of rows and columns in a 2-D matrix.
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1483
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1484 @node Character Strings in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1485 @subsection Character Strings in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1486
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1487 As mex-files do not make the distinction between single and double
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1488 quoted strings within Octave, there is perhaps less complexity in the
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1489 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
1490 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
1491 file @file{mystring.c}, as shown below.
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1492
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1493 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1494 @EXAMPLEFILE(mystring.c)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1495 @end example
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1496
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1497 @noindent
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1498 An example of its expected output is
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1499
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1500 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1501 @group
14856
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents: 14846
diff changeset
1502 mystring (["First String"; "Second String"])
18358
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1503 @result{} Second String
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1504 First String
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1505 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1506 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1507
7096
81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe]
jwe
parents: 7081
diff changeset
1508 Other functions in the mex interface for handling character strings are
81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe]
jwe
parents: 7081
diff changeset
1509 @code{mxCreateString}, @code{mxArrayToString}, and
81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe]
jwe
parents: 7081
diff changeset
1510 @code{mxCreateCharMatrixFromStrings}. In a mex-file, a character string
81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe]
jwe
parents: 7081
diff changeset
1511 is considered to be a vector rather than a matrix. This is perhaps an
81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe]
jwe
parents: 7081
diff changeset
1512 arbitrary distinction as the data in the mxArray for the matrix is
81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe]
jwe
parents: 7081
diff changeset
1513 consecutive in any case.
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1514
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1515 @node Cell Arrays with Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1516 @subsection Cell Arrays with Mex-Files
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1517
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1518 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
1519 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
1520 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
1521 as shown below.
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1522
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1523 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1524 @EXAMPLEFILE(mycell.c)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1525 @end example
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1526
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1527 @noindent
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1528 The output is identical to the oct-file version as well.
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1529
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1530 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1531 @group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1532 [b1, b2, b3] = mycell (@{1, [1, 2], "test"@})
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1533 @result{}
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1534 b1 = 1
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1535 b2 =
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1536
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1537 1 2
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1538
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1539 b3 = test
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1540 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1541 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1542
9080
ec41eabf4499 Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents: 9038
diff changeset
1543 Note in the example the use of the @code{mxDuplicateArray} function. This
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1544 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
1545 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
1546 setting Cell values, is @code{mxSetCell} and is defined as
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1547
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1548 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1549 void mxSetCell (mxArray *ptr, int idx, mxArray *val);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1550 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1551
7007
6304d9ea0a30 [project @ 2007-10-11 16:26:36 by jwe]
jwe
parents: 7001
diff changeset
1552 Finally, to create a cell array or matrix, the appropriate functions are
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1553
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1554 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1555 @group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1556 mxArray *mxCreateCellArray (int ndims, const int *dims);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1557 mxArray *mxCreateCellMatrix (int m, int n);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1558 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1559 @end example
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1560
6572
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
1561 @node Structures with Mex-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe]
jwe
parents: 6571
diff changeset
1562 @subsection Structures with Mex-Files
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1563
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1564 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
1565 @code{mxCreateStructMatrix} which creates a structure array with a two
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1566 dimensional matrix, or @code{mxCreateStructArray}.
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1567
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1568 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1569 @group
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1570 mxArray *mxCreateStructArray (int ndims, int *dims,
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1571 int num_keys,
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1572 const char **keys);
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1573 mxArray *mxCreateStructMatrix (int rows, int cols,
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1574 int num_keys,
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1575 const char **keys);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1576 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1577 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1578
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1579 Accessing the fields of the structure can then be performed with
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1580 @code{mxGetField} and @code{mxSetField} or alternatively with the
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1581 @code{mxGetFieldByNumber} and @code{mxSetFieldByNumber} functions.
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1582
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1583 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1584 @group
7081
503001863427 [project @ 2007-10-31 01:08:14 by jwe]
jwe
parents: 7018
diff changeset
1585 mxArray *mxGetField (const mxArray *ptr, mwIndex index,
503001863427 [project @ 2007-10-31 01:08:14 by jwe]
jwe
parents: 7018
diff changeset
1586 const char *key);
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1587 mxArray *mxGetFieldByNumber (const mxArray *ptr,
6686
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman]
dbateman
parents: 6606
diff changeset
1588 mwIndex index, int key_num);
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1589 void mxSetField (mxArray *ptr, mwIndex index,
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1590 const char *key, mxArray *val);
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1591 void mxSetFieldByNumber (mxArray *ptr, mwIndex index,
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1592 int key_num, mxArray *val);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1593 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1594 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1595
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1596 A difference between the oct-file interface to structures and the
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1597 mex-file version is that the functions to operate on structures in
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1598 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
1599 arrays of elements per @code{field}; Whereas, the oct-file structure
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1600 includes a Cell Array per field of the structure.
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1601
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1602 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
1603 found in the file @file{mystruct.c} shown below.
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1604
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1605 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1606 @EXAMPLEFILE(mystruct.c)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1607 @end example
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1608
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1609 An example of the behavior of this function within Octave is then
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1610
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1611 @example
18851
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18831
diff changeset
1612 @group
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1613 a(1).f1 = "f11"; a(1).f2 = "f12";
7081
503001863427 [project @ 2007-10-31 01:08:14 by jwe]
jwe
parents: 7018
diff changeset
1614 a(2).f1 = "f21"; a(2).f2 = "f22";
18358
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1615 b = mystruct (a);
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1616 @result{} field f1(0) = f11
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1617 field f1(1) = f21
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1618 field f2(0) = f12
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1619 field f2(1) = f22
18358
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1620 b
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1621 @result{} 2x2 struct array containing the fields:
17281
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents: 17152
diff changeset
1622
18358
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1623 this
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1624 that
17281
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents: 17152
diff changeset
1625
18358
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1626 b(3)
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1627 @result{} scalar structure containing the fields:
17281
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents: 17152
diff changeset
1628
18358
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1629 this = this3
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1630 that = that3
18851
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18831
diff changeset
1631 @end group
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1632 @end example
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1633
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1634 @node Sparse Matrices with Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1635 @subsection Sparse Matrices with Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1636
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1637 The Octave format for sparse matrices is identical to the mex format in
7001
8b0cfeb06365 [project @ 2007-10-10 18:02:59 by jwe]
jwe
parents: 6939
diff changeset
1638 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
1639 matrices are required to be two-dimensional. The only difference is that
6939
46d1ad37d943 [project @ 2007-10-01 16:12:20 by jwe]
jwe
parents: 6686
diff changeset
1640 the real and imaginary parts of the matrix are stored separately.
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1641
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1642 The mex-file interface, in addition to using @code{mxGetM}, @code{mxGetN},
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1643 @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
1644 @code{mxSetPr}, and @code{mxSetPi}, also supplies the following functions.
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1645
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1646 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1647 @group
6686
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman]
dbateman
parents: 6606
diff changeset
1648 mwIndex *mxGetIr (const mxArray *ptr);
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman]
dbateman
parents: 6606
diff changeset
1649 mwIndex *mxGetJc (const mxArray *ptr);
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman]
dbateman
parents: 6606
diff changeset
1650 mwSize mxGetNzmax (const mxArray *ptr);
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1651
6686
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman]
dbateman
parents: 6606
diff changeset
1652 void mxSetIr (mxArray *ptr, mwIndex *ir);
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman]
dbateman
parents: 6606
diff changeset
1653 void mxSetJc (mxArray *ptr, mwIndex *jc);
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman]
dbateman
parents: 6606
diff changeset
1654 void mxSetNzmax (mxArray *ptr, mwSize nzmax);
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1655 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1656 @end example
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1657
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1658 @noindent
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1659 @code{mxGetNzmax} gets the maximum number of elements that can be stored
18851
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18831
diff changeset
1660 in the sparse matrix. This is not necessarily the number of nonzero
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1661 elements in the sparse matrix. @code{mxGetJc} returns an array with one
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1662 additional value than the number of columns in the sparse matrix. The
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1663 difference between consecutive values of the array returned by
18851
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18831
diff changeset
1664 @code{mxGetJc} define the number of nonzero 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
1665 the sparse matrix. Therefore,
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1666
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1667 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1668 @group
6686
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman]
dbateman
parents: 6606
diff changeset
1669 mwSize nz, n;
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman]
dbateman
parents: 6606
diff changeset
1670 mwIndex *Jc;
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1671 mxArray *m;
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1672 @dots{}
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1673 n = mxGetN (m);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1674 Jc = mxGetJc (m);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1675 nz = Jc[n];
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1676 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1677 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1678
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1679 @noindent
18851
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18831
diff changeset
1680 returns the actual number of nonzero elements stored in the matrix in
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1681 @code{nz}. As the arrays returned by @code{mxGetPr} and @code{mxGetPi}
18851
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18831
diff changeset
1682 only contain the nonzero values of the matrix, we also need a pointer
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18831
diff changeset
1683 to the rows of the nonzero elements, and this is given by
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1684 @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
1685 mex-files is given by the file @file{mysparse.c} shown below.
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1686
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1687 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1688 @EXAMPLEFILE(mysparse.c)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1689 @end example
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1690
18358
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1691 A sample usage of @code{mysparse} is
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1692
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1693 @example
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1694 @group
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1695 sm = sparse ([1, 0; 0, pi]);
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1696 mysparse (sm)
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1697 @result{}
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1698 Matrix is 2-by-2 real sparse matrix with 2 elements
18851
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18831
diff changeset
1699 last nonzero element (2, 2) = 3.14159
18358
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1700 @end group
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1701 @end example
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter.
Rik <rik@octave.org>
parents: 18075
diff changeset
1702
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1703 @node Calling Other Functions in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1704 @subsection Calling Other Functions in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1705
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1706 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
1707 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
1708 can be see in the example below.
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1709
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1710 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1711 @EXAMPLEFILE(myfeval.c)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1712 @end example
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1713
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1714 If this code is in the file @file{myfeval.c}, and is compiled to
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1715 @file{myfeval.mex}, then an example of its use is
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1716
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1717 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1718 @group
14856
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents: 14846
diff changeset
1719 a = myfeval ("sin", 1)
18367
d1e16bdb3958 myfeval.c: Fix segfault in mex example code.
Rik <rik@octave.org>
parents: 18358
diff changeset
1720 @result{} Starting file myfeval.mex
d1e16bdb3958 myfeval.c: Fix segfault in mex example code.
Rik <rik@octave.org>
parents: 18358
diff changeset
1721 I have 2 inputs and 1 outputs
d1e16bdb3958 myfeval.c: Fix segfault in mex example code.
Rik <rik@octave.org>
parents: 18358
diff changeset
1722 I'm going to call the interpreter function sin
d1e16bdb3958 myfeval.c: Fix segfault in mex example code.
Rik <rik@octave.org>
parents: 18358
diff changeset
1723 a = 0.84147
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1724 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1725 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1726
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1727 Note that it is not possible to use function handles or inline functions
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1728 within a mex-file.
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1729
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1730 @c @node Application Programming Interface for Mex-Files
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1731 @c @subsection Application Programming Interface for Mex-Files
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1732 @c
6593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman]
dbateman
parents: 6583
diff changeset
1733 @c WRITE ME, refer to mex.h and mexproto.h
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1734
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1735 @node Standalone Programs
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1736 @section Standalone Programs
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1737
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1738 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
1739 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
1740 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
1741 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
1742 @file{liboctave.so}.
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1743
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1744 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1745 @EXAMPLEFILE(standalone.cc)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1746 @end example
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1747
6580
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman]
dbateman
parents: 6578
diff changeset
1748 @noindent
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1749 mkoctfile can be used to build a standalone application with a
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1750 command like
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1751
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1752 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1753 @group
8097
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents: 7354
diff changeset
1754 $ 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
1755 $ ./standalone
6569
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1756 Hello Octave world!
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1757 11 12
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1758 21 22
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1759 $
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1760 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1761 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe]
jwe
parents:
diff changeset
1762
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1763 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
1764 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
1765 allows the Octave math libraries to be used by an application. It does
18534
f51c1498b9f3 doc: Replace "builtin" with "built-in" for consistency and correctness.
Rik <rik@octave.org>
parents: 18369
diff changeset
1766 not, however, allow the script files, oct-files, or built-in functions of
9080
ec41eabf4499 Cleanup documentation files dynamic.texi, testfun.texi, tips.texi
Rik <rdrider0-list@yahoo.com>
parents: 9038
diff changeset
1767 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
1768 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
1769 seen in the code
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents: 7354
diff changeset
1770
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1771 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1772 @EXAMPLEFILE(embedded.cc)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1773 @end example
8097
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents: 7354
diff changeset
1774
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents: 7354
diff changeset
1775 @noindent
16867
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions.
Rik <rik@octave.org>
parents: 16483
diff changeset
1776 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
1777
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents: 7354
diff changeset
1778 @example
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents: 7354
diff changeset
1779 @group
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents: 7354
diff changeset
1780 $ 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
1781 $ ./embedded
16483
fcf1b0b52083 Use a better example of gcd() in embedded.cc
Rik <rik@octave.org>
parents: 16482
diff changeset
1782 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
1783 $
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents: 7354
diff changeset
1784 @end group
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents: 7354
diff changeset
1785 @end example
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program
David Bateman <dbateman@free.fr>
parents: 7354
diff changeset
1786
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1787 It is worth noting that, if only built-in functions are to be called from
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1788 a C++ standalone program, then it does not need to initialize the
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1789 interpreter to do so. The general rule is that, for a built-in
17949
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1790 function named @code{function_name} in the interpreter, there will be
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1791 a C++ function named @code{Ffunction_name} (note the prepended capital
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1792 @code{F}) accessible in the C++ API@. The declarations for all built-in
17949
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1793 functions are collected in the header file @code{builtin-defun-decls.h}.
18075
24759ac2b8cb doc: Periodic spellcheck of documentation
Rik <rik@octave.org>
parents: 17949
diff changeset
1794 This feature should be used with care as the list of built-in functions can
24759ac2b8cb doc: Periodic spellcheck of documentation
Rik <rik@octave.org>
parents: 17949
diff changeset
1795 change. No guarantees can be made that a function that is currently built in
24759ac2b8cb doc: Periodic spellcheck of documentation
Rik <rik@octave.org>
parents: 17949
diff changeset
1796 won't be implemented as a .m file or as a dynamically linked function in the
18851
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18831
diff changeset
1797 future. An example of how to call built-in functions from C++ can be seen in
9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage.
Rik <rik@octave.org>
parents: 18831
diff changeset
1798 the code
17949
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1799
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1800 @example
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1801 @EXAMPLEFILE(standalonebuiltin.cc)
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1802 @end example
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1803
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1804 @noindent
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1805 which, again, is compiled and run as a standalone application with
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1806
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1807 @example
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1808 @group
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1809 $ mkoctfile --link-stand-alone standalonebuiltin.cc -o standalonebuiltin
19627
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 18987
diff changeset
1810 $ ./standalonebuiltin
17949
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1811 This is a matrix:
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1812 11 12
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1813 21 22
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1814
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1815 This is the norm of the matrix:
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1816 34.4952
18367
d1e16bdb3958 myfeval.c: Fix segfault in mex example code.
Rik <rik@octave.org>
parents: 18358
diff changeset
1817 $
17949
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1818 @end group
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1819 @end example
3341d2f1e5db Document calling DEFUN functions in C++.
Carlo de Falco <cdf@users.sourceforge.net>
parents: 17744
diff changeset
1820