octave: doc/interpreter/external.txi annotate

annotate doc/interpreter/external.txi @ 25054:6652d3823428 stable

maint: Update copyright dates in all source files.

author	John W. Eaton <jwe@octave.org>
date	Fri, 30 Mar 2018 09:19:05 -0400
parents	a895967fd5a7
children	13fd0610480f

rev	line source
25054 6652d3823428 maint: Update copyright dates in all source files. John W. Eaton <jwe@octave.org> parents: 24987 diff changeset	1 @c Copyright (C) 2007-2018 John W. Eaton and David Bateman
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2 @c Copyright (C) 2010 Martin Hepperle
7018 fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	3 @c Copyright (C) 2007 Paul Thomas and Christoph Spiel
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	4 @c
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	5 @c This file is part of Octave.
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	6 @c
24534 194eb4bd202b maint: Update punctuation for GPL v3 license text. Rik <rik@octave.org> parents: 23567 diff changeset	7 @c Octave is free software: you can redistribute it and/or modify it
22755 3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22482 diff changeset	8 @c under the terms of the GNU General Public License as published by
24534 194eb4bd202b maint: Update punctuation for GPL v3 license text. Rik <rik@octave.org> parents: 23567 diff changeset	9 @c the Free Software Foundation, either version 3 of the License, or
22755 3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22482 diff changeset	10 @c (at your option) any later version.
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	11 @c
22755 3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22482 diff changeset	12 @c Octave is distributed in the hope that it will be useful, but
3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22482 diff changeset	13 @c WITHOUT ANY WARRANTY; without even the implied warranty of
3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22482 diff changeset	14 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22482 diff changeset	15 @c GNU General Public License for more details.
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	16 @c
7018 fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	17 @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	18 @c along with Octave; see the file COPYING. If not, see
24534 194eb4bd202b maint: Update punctuation for GPL v3 license text. Rik <rik@octave.org> parents: 23567 diff changeset	19 @c <https://www.gnu.org/licenses/>.
6578 fbc16fe0e86a [project @ 2007-04-25 16:04:59 by jwe] jwe parents: 6577 diff changeset	20
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	21 @node External Code Interface
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	22 @appendix External Code Interface
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	23 @cindex dynamic-linking
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	24 @cindex Dynamically Linked Functions
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	25 @cindex Octave API
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	26
18953 bcbd309bf272 doc: Fix quote character at beginning of External Code Interfaces chapter. Rik <rik@octave.org> parents: 18797 diff changeset	27 "The sum of human wisdom is not contained in any one language"
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	28
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	29 --- Ezra Pound
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	30
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	31 Octave is a fantastic language for solving many problems in science and
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	32 engineering. However, it is not the only computer language and there are times
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	33 when you may want to use code written in other languages. Good reasons for
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	34 doing so include: 1) not re-inventing the wheel; existing function libraries
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	35 which have been thoroughly tested and debugged or large scale simulation
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	36 codebases are a good example, 2) accessing unique capabilities of a different
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	37 language; for example the well-known regular expression functions of Perl (but
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	38 don't do that because @code{regexp} already exists in Octave).
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	39
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	40 Performance should generally @strong{not} be a reason for using compiled
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	41 extensions. Although compiled extensions can run faster, particularly if they
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	42 replace a loop in Octave code, this is almost never the best path to take.
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	43 First, there are many techniques to speed up Octave performance while remaining
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	44 within the language. Second, Octave is a high-level language that makes it
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	45 easy to perform common mathematical tasks. Giving that up means shifting the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	46 focus from solving the real problem to solving a computer programming problem.
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	47 It means returning to low-level constructs such as pointers, memory management,
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	48 mathematical overflow/underflow, etc. Because of the low level nature, and the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	49 fact that the compiled code is executed outside of Octave, there is the very
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	50 real possibility of crashing the interpreter and losing work.
16867 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
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	59 Even when a function already exists outside the language, it may be better to
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	60 simply reproduce the behavior in an m-file rather than attempt to interface to
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	61 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
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	68 (@pxref{Vectorization and Faster Code Execution}) which not only makes the code
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	69 concise and more understandable but improves performance (10X-100X). If loops
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	70 must be used, make sure that the allocation of space for variables takes place
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	71 outside the loops using an assignment to a matrix of the right size, or zeros.
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	72
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	73 @item
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	74 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	75 routines?
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	76
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	77 These routines are highly optimized and many do not carry the overhead of being
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	78 interpreted.
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	79
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	80 @item
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	81 Does writing a dynamically linked function represent a useful investment of
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	82 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	83
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	84 It will take time to learn Octave's interface for external code and there will
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	85 inevitably be issues with tools such as compilers.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	86 @end itemize
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	87
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	88 With that said, Octave offers a versatile interface for including chunks of
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	89 compiled code as dynamically linked extensions. These dynamically linked
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	90 functions can be called from the interpreter in the same manner as any ordinary
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	91 function. The interface is bi-directional and external code can call Octave
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	92 functions (like @code{plot}) which otherwise might be very difficult to
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	93 develop.
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	94
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	95 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	96 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	97 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	98 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	99 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	100
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	101 Because many other languages provide C or C++ APIs it is relatively simple to
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	102 build bridges between Octave and other languages. This is also a way to bridge
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	103 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	104
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	105 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	106 * Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	107 * Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	108 * Standalone Programs::
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	109 * Java Interface::
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::
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	131 * Documentation and Testing of Oct-Files::
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 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
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	138 Oct-files are pieces of C++ code that have been compiled with the Octave API
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	139 into a dynamically loadable object. They take their name from the file which
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	140 contains the object which has the extension @file{.oct}.
16867 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
21530 7c143e73e921 doc: Don't create end-of-sentence period with "etc." in Texinfo. Rik <rik@octave.org> parents: 21319 diff changeset	143 paths for header files, etc.@: is a difficult task. Octave automates this by
16867 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
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	149 Consider the following short example which introduces the basics of writing a
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	150 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
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	158 The first critical line is @code{#include <octave/oct.h>} which makes available
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	159 most of the definitions necessary for a C++ oct-file. Note that
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	160 @file{octave/oct.h} is a C++ header and cannot be directly @code{#include}'ed
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	161 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
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	163 Included by @file{oct.h} is a definition for the macro @w{@code{DEFUN_DLD}}
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	164 which creates a dynamically loaded function. This macro takes four arguments:
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	165
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	166 @enumerate 1
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	167 @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	168
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	169 @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	170
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	171 @item The number of output arguments, which can be---and often is---omitted if
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	172 not used, and
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	173
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	174 @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	175 @end enumerate
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	176
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9080 diff changeset	177 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	178 @code{octave_value_list}.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	179
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	180 There are a couple of important considerations in the choice of function name.
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	181 First, it must be a valid Octave function name and so must be a sequence of
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	182 letters, digits, and underscores not starting with a digit. Second, as Octave
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	183 uses the function name to define the filename it attempts to find the function
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	184 in, the function name in the @w{@code{DEFUN_DLD}} macro must match the filename
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	185 of the oct-file. Therefore, the above function should be in a file
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	186 @file{helloworld.cc}, and would be compiled to an oct-file using the command
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	187
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	188 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	189 mkoctfile helloworld.cc
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	190 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	191
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	192 This will create a file called @file{helloworld.oct} that is the compiled
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	193 version of the function. It should be noted that it is perfectly acceptable to
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	194 have more than one @w{@code{DEFUN_DLD}} function in a source file. However,
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	195 there must either be a symbolic link to the oct-file for each of the functions
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	196 defined in the source code with the @w{@code{DEFUN_DLD}} macro or the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	197 @code{autoload} (@ref{Function Files}) function should be used.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	198
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	199 The rest of the function shows how to find the number of input arguments, how
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	200 to print through the Octave pager, and how to return from the function. After
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	201 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	202
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	203 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	204 @group
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	205 helloworld (1, 2, 3)
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	206 @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	207 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	208 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	209
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	210 Subsequent sections show how to use specific classes from Octave's core
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	211 internals. Base classes like @code{dMatrix} (a matrix of double values) are
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	212 found in the directory @file{liboctave/array}. The definitive reference for
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	213 how to use a particular class is the header file itself. However, it is often
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	214 enough simply to study the examples in the manual in order to be able to use a
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	215 class.
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	216
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	217 @node Matrices and Arrays in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	218 @subsection Matrices and Arrays in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	219
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	220 Octave supports a number of different array and matrix classes, the majority of
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	221 which are based on the @code{Array} class. The exception are the sparse matrix
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	222 types discussed separately below. There are three basic matrix types:
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	223
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	224 @table @code
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	225 @item Matrix
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	226 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	227
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	228 @item ComplexMatrix
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	229 A complex matrix class defined in @file{CMatrix.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 BoolMatrix
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	232 A boolean matrix class defined in @file{boolMatrix.h}
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	233 @end table
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	234
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	235 These are the basic two-dimensional matrix types of Octave. In addition there
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	236 are a number of multi-dimensional array types including
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	237
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	238 @table @code
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	239 @item NDArray
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	240 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	241
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	242 @item ComplexNDarray
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	243 A complex array class defined in @file{CNDArray.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 boolNDArray
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	246 A boolean array class defined in @file{boolNDArray.h}
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	247
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	248 @item int8NDArray
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	249 @itemx int16NDArray
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	250 @itemx int32NDArray
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	251 @itemx int64NDArray
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	252 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	253 @file{int8NDArray.h}, @file{int16NDArray.h}, etc.
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	254
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	255 @item uint8NDArray
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	256 @itemx uint16NDArray
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	257 @itemx uint32NDArray
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	258 @itemx uint64NDArray
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	259 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	260 @file{uint8NDArray.h}, @file{uint16NDArray.h}, etc.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	261 @end table
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	262
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	263 There are several basic ways of constructing matrices or multi-dimensional
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	264 arrays. Using the class @code{Matrix} as an example one can
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	265
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	266 @itemize @bullet
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	267 @item
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	268 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	269
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	270 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	271 Matrix a;
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	272 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	273
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	274 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	275
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	276 @item
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	277 Define the dimensions of the matrix or array with a dim_vector which has the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	278 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	279
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	280 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	281 @group
20187 998881b6cdef external.txi: Fix example case for dim_vector (bug #45100). Piotr Held <pjheld@gmail.com> parents: 19721 diff changeset	282 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	283 Matrix a (dv);
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	284 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	285 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	286
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	287 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	288
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	289 @item
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	290 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	291
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	292 @example
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	293 Matrix a (2, 2)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	294 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	295
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	296 This constructor can @strong{only} be used with matrix types.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	297 @end itemize
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	298
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	299 These types all share a number of basic methods and operators. Many bear a
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	300 resemblance to functions that exist in the interpreter. A selection of useful
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	301 methods include
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	302
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	303 @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	304 @deftypefnx {Method} {T&} elem (octave_idx_type)
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	305 The @code{()} operator or @code{elem} method allow the values of the matrix or
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	306 array to be read or set. These methods take a single argument, which is of
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	307 type @code{octave_idx_type}, that is the index into the matrix or array.
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	308 Additionally, the matrix type allows two argument versions of the @code{()}
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	309 operator and @code{elem} method, giving the row and column index of the value
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	310 to get or set.
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	311 @end deftypefn
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	312
7001 8b0cfeb06365 [project @ 2007-10-10 18:02:59 by jwe] jwe parents: 6939 diff changeset	313 Note that these functions do significant error checking and so in some
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	314 circumstances the user might prefer to access the data of the array or matrix
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	315 directly through the @code{fortran_vec} method discussed below.
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	316
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	317 @deftypefn {Method} {octave_idx_type} numel (void) const
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	318 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	319 @end deftypefn
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} {size_t} byte_size (void) const
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	322 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	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} {dim_vector} dims (void) const
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	326 The dimensions of the matrix or array in value of type @code{dim_vector}.
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} {int} ndims (void) const
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	330 The number of dimensions of the matrix or array. Matrices are always 2-D, but
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	331 arrays can be N-dimensional.
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	332 @end deftypefn
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	333
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	334 @deftypefn {Method} {void} resize (const dim_vector&)
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	335 @deftypefnx {Method} {void} resize (nrows, ncols)
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	336 A method taking either an argument of type @code{dim_vector}, or, in the case
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	337 of a matrix, two arguments of type @code{octave_idx_type} defining the number
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	338 of rows and columns in the matrix.
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	339 @end deftypefn
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	340
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	341 @deftypefn {Method} {T*} fortran_vec (void)
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	342 This method returns a pointer to the underlying data of the matrix or array so
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	343 that it can be manipulated directly, either within Octave or by an external
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	344 library.
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	345 @end deftypefn
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	346
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	347 Operators such as @code{+}, @code{-}, or @code{*} can be used on the majority
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	348 of the matrix and array types. In addition there are a number of methods that
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	349 are of interest only for matrices such as @code{transpose}, @code{hermitian},
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	350 @code{solve}, etc.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	351
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	352 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	353 @w{@code{DEFUN_DLD}} function is as follows
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	354
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	355 @example
21316 6cc091426e52 doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 20535 diff changeset	356 @group
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	357 @EXAMPLEFILE(addtwomatrices.cc)
21316 6cc091426e52 doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 20535 diff changeset	358 @end group
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	359 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	360
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	361 To avoid segmentation faults causing Octave to abort, this function explicitly
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	362 checks that there are sufficient arguments available before accessing these
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	363 arguments. It then obtains two multi-dimensional arrays of type @code{NDArray}
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	364 and adds these together. Note that the @code{array_value} method is called
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	365 without using the @code{is_matrix_type} method. If an error occurs when
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	366 attempting to extract the value, Octave will print a message and throw an
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	367 exception. The reason to prefer this coding structure is that the arguments
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	368 might be a type which is not an @code{NDArray}, but for which it would make
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	369 sense to convert them to one. The @code{array_value} method allows this
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	370 conversion to be performed transparently when possible. If you need to catch
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	371 errors like this, and perform some kind of cleanup or other operation, you can
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	372 catch the @code{octave_execution_error} exception.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	373
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	374 @code{A + B}, operating on two @code{NDArray} objects returns an
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	375 @code{NDArray}, which is cast to an @code{octave_value} on the return from the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	376 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	377
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	378 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	379 @group
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	380 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	381 @result{} 2 1
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	382 1 2
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	383 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	384 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	385
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	386 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	387 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	388 listed below.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	389
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	390 @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	391 @headitem Type @tab Function @tab Source Code
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	392 @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	393 @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	394 @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	395 @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	396 @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	397 @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	398 @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	399 @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	400 @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	401 @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	402 @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	403 @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	404 @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	405 @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	406 @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	407 @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	408 @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	409 @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	410 @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	411 @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	412 @end multitable
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	413
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	414 @node Character Strings in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	415 @subsection Character Strings in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	416
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	417 A character string in Octave is just a special @code{Array} class. Consider
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	418 the example:
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	419
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	420 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	421 @EXAMPLEFILE(stringdemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	422 @end example
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	423
9080 ec41eabf4499 Cleanup documentation files dynamic.texi, testfun.texi, tips.texi Rik <rdrider0-list@yahoo.com> parents: 9038 diff changeset	424 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	425
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	426 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	427 @group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	428 s0 = ["First String"; "Second String"];
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	429 [s1,s2] = stringdemo (s0)
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	430 @result{} s1 = Second String
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	431 First String
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	432
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	433 @result{} s2 = First String
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	434 Second String
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	435
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	436 typeinfo (s2)
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	437 @result{} sq_string
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	438 typeinfo (s1)
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	439 @result{} string
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	440 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	441 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	442
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	443 One additional complication of strings in Octave is the difference between
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	444 single quoted and double quoted strings. To find out if an @code{octave_value}
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	445 contains a single or double quoted string use one of the predicate tests shown
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	446 below.
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	447
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	448 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	449 @group
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	450 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	451 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	452 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	453 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	454 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	455 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	456
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	457 Note, however, that both types of strings are represented by the
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	458 @code{charNDArray} type, and so when assigning to an @code{octave_value}, the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	459 type of string should be specified. For example:
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	460
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	461 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	462 @group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	463 octave_value_list retval;
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	464 charNDArray ch;
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	465 @dots{}
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	466 // Create single quoted string
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	467 retval(1) = octave_value (ch); // default constructor is sq_string
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	468 OR
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, '\''); // explicitly create sq_string
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	470
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	471 // 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	472 retval(0) = octave_value (ch, '"');
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	473 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	474 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	475
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	476 @node Cell Arrays in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	477 @subsection Cell Arrays in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	478
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	479 Octave's cell type is also available from within oct-files. A cell array is
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	480 just an @code{Array} of @code{octave_value}s, and thus each element of the cell
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	481 array can be treated like any other @code{octave_value}. A simple example is
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	482
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	483 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	484 @EXAMPLEFILE(celldemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	485 @end example
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	486
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	487 Note that cell arrays are used less often in standard oct-files and so the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	488 @file{Cell.h} header file must be explicitly included. The rest of the example
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	489 extracts the @code{octave_value}s one by one from the cell array and returns
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	490 them as individual output arguments. For example:
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	491
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	492 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	493 @group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	494 [b1, b2, b3] = celldemo (@{1, [1, 2], "test"@})
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	495 @result{}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	496 b1 = 1
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	497 b2 =
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	498
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	499 1 2
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	500
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	501 b3 = test
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	502 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	503 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	504
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	505 @node Structures in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	506 @subsection Structures in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	507
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	508 A structure in Octave is a map between a number of fields represented and their
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	509 values. The Standard Template Library @code{map} class is used, with the pair
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	510 consisting of a @code{std::string} and an Octave @code{Cell} variable.
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	511
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	512 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	513
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	514 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	515 @EXAMPLEFILE(structdemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	516 @end example
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	517
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	518 An example of its use is
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	519
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	520 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	521 @group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	522 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	523 structdemo (x, "b")
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	524 @result{} selected = test
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	525 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	526 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	527
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	528 The example above specifically uses the @code{octave_scalar_map} class which is
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	529 for representing a single struct. For structure arrays, the @code{octave_map}
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	530 class is used instead. The commented code shows how the demo could be modified
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	531 to handle a structure array. In that case, the @code{contents} method returns
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	532 a @code{Cell} which may have more than one element. Therefore, to obtain the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	533 underlying @code{octave_value} in the single struct example we would write
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	534
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	535 @example
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	536 octave_value tmp = arg0.contents (arg1)(0);
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	537 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	538
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	539 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	540 where the trailing @code{(0)} is the @code{()} operator on the @code{Cell}
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	541 object. If this were a true structure array with multiple elements we could
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	542 iterate over the elements using the @code{()} operator.
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	543
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	544 Structures are a relatively complex data container and there are more functions
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	545 available in @file{oct-map.h} which make coding with them easier than relying
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	546 on just @code{contents}.
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	547
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	548 @node Sparse Matrices in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	549 @subsection Sparse Matrices in Oct-Files
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	550
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	551 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	552
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	553 @table @code
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	554 @item SparseMatrix
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	555 A double precision sparse matrix class
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	556
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	557 @item SparseComplexMatrix
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	558 A complex sparse matrix class
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	559
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	560 @item SparseBoolMatrix
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	561 A boolean sparse matrix class
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	562 @end table
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	563
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	564 All of these classes inherit from the @code{Sparse<T>} template class, and so
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	565 all have similar capabilities and usage. The @code{Sparse<T>} class was based
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	566 on Octave's @code{Array<T>} class and users familiar with Octave's
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	567 @code{Array} classes will be comfortable with the use of the sparse classes.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	568
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	569 The sparse classes will not be entirely described in this section, due to their
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	570 similarity with the existing @code{Array} classes. However, there are a few
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	571 differences due the nature of sparse objects, and these will be described.
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	572 First, although it is fundamentally possible to have N-dimensional sparse
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	573 objects, the Octave sparse classes do not allow them at this time; All
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	574 instances of the sparse classes @strong{must} be 2-dimensional. This means
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	575 that @code{SparseMatrix} is actually more similar to Octave's @code{Matrix}
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	576 class than it is to the @code{NDArray} class.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	577
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	578 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	579 * Array and Sparse Class Differences::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	580 * Creating Sparse Matrices in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	581 * Using Sparse Matrices in Oct-Files::
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	582 @end menu
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	583
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	584 @node Array and Sparse Class Differences
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	585 @subsubsection Array and Sparse Class Differences
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	586
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	587 The number of elements in a sparse matrix is considered to be the number
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	588 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	589
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	590 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	591 @group
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	592 SparseMatrix sm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	593 @dots{}
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	594 int nnz = sm.nelem ();
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	595 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	596 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	597
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	598 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	599 returns the number of nonzero elements (like the interpreter function
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	600 @code{nnz}). If the user really requires the number of elements in the matrix,
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	601 including the nonzero elements, they should use @code{numel} rather than
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	602 @code{nelem}. Note that for very large matrices, where the product of the two
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	603 dimensions is larger than the representation of an unsigned int, @code{numel}
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	604 can overflow. An example is @code{speye (1e6)} which will create a matrix with
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	605 a million rows and columns, but only a million nonzero elements. In this case,
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	606 the number of rows multiplied by the number of columns is more than two hundred
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	607 times the maximum value that can be represented by an unsigned 32-bit int. The
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	608 use of @code{numel} should, therefore, be avoided unless it is known that it
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	609 will not overflow.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	610
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	611 Extreme care is also required when using the @code{elem} method or the
24987 a895967fd5a7 doc: grammarcheck manual (.txi) ahead of 4.4 release. Rik <rik@octave.org>* parents: 24534 diff changeset	612 @code{()} operator which perform essentially the same function. The reason is
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	613 that if a sparse object is non-const, then Octave will assume that a request
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	614 for a zero element in a sparse matrix is in fact a request to create this
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	615 element so it can be filled. Therefore, a piece of code like
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	616
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	617 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	618 @group
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	619 SparseMatrix sm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	620 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	621 for (int j = 0; j < nc; j++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	622 for (int i = 0; i < nr; i++)
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	623 std::cerr << " (" << i << "," << j << "): " << sm(i,j) << "\n";
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	624 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	625 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	626
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	627 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	628 is a great way of turning a sparse matrix into a dense one, and a very slow
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	629 way at that since it reallocates the sparse object for each zero element in the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	630 matrix.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	631
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	632 A simple way of preventing the above from happening is to create a temporary
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	633 constant version of the sparse matrix. Note that only the container for the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	634 sparse matrix will be copied, while the actual representation of the data will
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	635 be shared between the two versions of the sparse matrix; This is not a costly
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	636 operation. The example above, re-written to prevent sparse-to-dense
23082 e8d64dce0afd maint: strip trailing whitespace from source files. John W. Eaton <jwe@octave.org> parents: 22970 diff changeset	637 conversion, is
6569 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 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	640 @group
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	641 SparseMatrix sm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	642 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	643 const SparseMatrix tmp (sm);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	644 for (int j = 0; j < nc; j++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	645 for (int i = 0; i < nr; i++)
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	646 std::cerr << " (" << i << "," << j << "): " << tmp(i,j) << "\n";
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	647 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	648 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	649
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	650 Finally, because the sparse types aren't represented by a contiguous block of
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	651 memory, the @nospell{@code{fortran_vec}} method of @code{Array<T>} is not
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	652 available. It is, however, replaced by three separate methods @code{ridx},
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	653 @code{cidx}, and @code{data}, that access the raw compressed column format that
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	654 Octave sparse matrices are stored in. These methods can be used in a manner
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	655 similar to @code{elem} to allow the matrix to be accessed or filled. However,
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	656 it is up to the user to respect the sparse matrix compressed column format or
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	657 the matrix will become corrupted.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	658
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	659 @node Creating Sparse Matrices in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	660 @subsubsection Creating Sparse Matrices in Oct-Files
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	661
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	662 There are two useful strategies for creating a sparse matrix. The first is to
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	663 create three vectors representing the row index, column index, and data values,
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	664 and from these create the matrix. The second alternative is to create a sparse
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	665 matrix with the appropriate amount of space, and then fill in the values. Both
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	666 techniques have their advantages and disadvantages.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	667
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	668 Below is an example of creating a small sparse matrix using the first technique
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	669
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	670 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	671 @group
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	672 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	673 nz = 4, nr = 3, nc = 4;
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	674
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	675 ColumnVector ridx (nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	676 ColumnVector cidx (nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	677 ColumnVector data (nz);
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	678
18797 96f22d6674c4 Fix incorrect sparse matrix example code in oct-file chapter (bug #41799). Rik <rik@octave.org> parents: 18790 diff changeset	679 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: 18790 diff changeset	680 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: 18790 diff changeset	681 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: 18790 diff changeset	682 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	683 SparseMatrix sm (data, ridx, cidx, nr, nc);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	684 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	685 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	686
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	687 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	688 which creates the matrix given in section @ref{Storage of Sparse Matrices}.
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	689 Note that the compressed matrix format is not used at the time of the creation
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	690 of the matrix itself, but is used internally.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	691
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	692 As discussed in the chapter on Sparse Matrices, the values of the sparse matrix
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	693 are stored in increasing column-major ordering. Although the data passed by
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	694 the user need not respect this requirement, pre-sorting the data will
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	695 significantly speed up creation of the sparse matrix.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	696
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	697 The disadvantage of this technique for creating a sparse matrix is that there
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	698 is a brief time when two copies of the data exist. For extremely memory
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	699 constrained problems this may not be the best technique for creating a sparse
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	700 matrix.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	701
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	702 The alternative is to first create a sparse matrix with the desired number of
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	703 nonzero elements and then later fill those elements in. Sample code:
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	704
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	705 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	706 @group
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	707 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	708 nz = 4, nr = 3, nc = 4;
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	709 SparseMatrix sm (nr, nc, nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	710 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	711 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	712 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	713
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	714 This creates the same matrix as previously. Again, although not strictly
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	715 necessary, it is significantly faster if the sparse matrix is created and the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	716 elements are added in column-major ordering. The reason for this is that when
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	717 elements are inserted at the end of the current list of known elements then no
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	718 element in the matrix needs to be moved to allow the new element to be
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	719 inserted; Only the column indices need to be updated.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	720
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	721 There are a few further points to note about this method of creating a sparse
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	722 matrix. First, it is possible to create a sparse matrix with fewer elements
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	723 than are actually inserted in the matrix. Therefore,
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	724
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	725 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	726 @group
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	727 int nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	728 nr = 3, nc = 4;
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	729 SparseMatrix sm (nr, nc, 0);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	730 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	731 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	732 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	733
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	734 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	735 is perfectly valid. However, it is a very bad idea because as each new element
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	736 is added to the sparse matrix the matrix needs to request more space and
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	737 reallocate memory. This is an expensive operation that will significantly slow
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	738 this means of creating a sparse matrix. It is possible to create a sparse
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	739 matrix with excess storage, so having @var{nz} greater than 4 in this example
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	740 is also valid. The disadvantage is that the matrix occupies more memory than
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	741 strictly needed.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	742
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	743 Of course, it is not always possible to know the number of nonzero elements
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	744 prior to filling a matrix. For this reason the additional unused storage of a
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	745 sparse matrix can be removed after its creation with the @code{maybe_compress}
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	746 function. In addition to deallocating unused storage, @code{maybe_compress}
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	747 can also remove zero elements from the matrix. The removal of zero elements
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	748 from the matrix is controlled by setting the argument of the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	749 @code{maybe_compress} function to be @code{true}. However, the cost of
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	750 removing the zeros is high because it implies re-sorting the elements. If
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	751 possible, it is better for the user to avoid adding the unnecessary zeros in
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	752 the first place. 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	753
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	754 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	755 @group
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	756 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	757 nz = 6, nr = 3, nc = 4;
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	758
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	759 SparseMatrix sm1 (nr, nc, nz);
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	760 sm1(0,0) = 1; sm1(0,1) = 2; sm1(1,3) = 3; sm1(2,3) = 4;
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	761 sm1.maybe_compress (); // No zero elements were added
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	762
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	763 SparseMatrix sm2 (nr, nc, nz);
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	764 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	765 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	766 sm2.maybe_compress (true); // Zero elements were added
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	767 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	768 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	769
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	770 The use of the @code{maybe_compress} function should be avoided if possible as
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	771 it will slow the creation of the matrix.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	772
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	773 A third means of creating a sparse matrix is to work directly with the data in
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	774 compressed row format. An example of this advanced technique might be
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	775
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	776 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	777 octave_value arg;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	778 @dots{}
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	779 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	780 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	781 SparseMatrix sm (nr, nc, nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	782 Matrix m = arg.matrix_value ();
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	783
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	784 int ii = 0;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	785 sm.cidx (0) = 0;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	786 for (int j = 1; j < nc; j++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	787 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	788 for (int i = 0; i < nr; i++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	789 @{
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	790 double tmp = m(i,j);
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	791 if (tmp != 0.)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	792 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	793 sm.data(ii) = tmp;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	794 sm.ridx(ii) = i;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	795 ii++;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	796 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	797 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	798 sm.cidx(j+1) = ii;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	799 @}
18790 322eb69e30ad doc: Fix some Latin wording in documentation. Rik <rik@octave.org> parents: 18534 diff changeset	800 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	801 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	802
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	803 @noindent
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	804 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	805
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	806 Finally, it may sometimes arise that the amount of storage initially created is
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	807 insufficient to completely store the sparse matrix. Therefore, the method
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	808 @code{change_capacity} exists to reallocate the sparse memory. The above
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	809 example would then be modified as
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	810
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	811 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	812 octave_value arg;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	813 @dots{}
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	814 int nz, nr, nc;
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	815 nz = 6, nr = 3, nc = 4; // Guess the number of nz elements
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	816 SparseMatrix sm (nr, nc, nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	817 Matrix m = arg.matrix_value ();
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	818
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	819 int ii = 0;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	820 sm.cidx (0) = 0;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	821 for (int j = 1; j < nc; j++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	822 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	823 for (int i = 0; i < nr; i++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	824 @{
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	825 double tmp = m(i,j);
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	826 if (tmp != 0.)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	827 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	828 if (ii == nz)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	829 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	830 nz += 2; // Add 2 more elements
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	831 sm.change_capacity (nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	832 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	833 sm.data(ii) = tmp;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	834 sm.ridx(ii) = i;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	835 ii++;
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 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	838 sm.cidx(j+1) = ii;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	839 @}
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	840 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	841 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	842
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	843 Note that both increasing and decreasing the number of nonzero elements in a
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	844 sparse matrix is expensive as it involves memory reallocation. Also because
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	845 parts of the matrix, though not its entirety, exist as old and new copies at
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	846 the same time, additional memory is needed. Therefore, if possible avoid
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	847 changing capacity.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	848
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	849 @node Using Sparse Matrices in Oct-Files
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	850 @subsubsection Using Sparse Matrices in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	851
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	852 Most of the same operators and functions for sparse matrices that are available
23567 71bfd507663c doc: Periodic spellcheck of documentation. Rik <rik@octave.org> parents: 23565 diff changeset	853 from the Octave interpreter are also available within oct-files. The basic
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	854 means of extracting a sparse matrix from an @code{octave_value}, and returning
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	855 it as an @code{octave_value}, can be seen in the following example.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	856
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	857 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	858 @group
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	859 octave_value_list retval;
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	860
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	861 SparseMatrix sm = args(0).sparse_matrix_value ();
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	862 SparseComplexMatrix scm = args(1).sparse_complex_matrix_value ();
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	863 SparseBoolMatrix sbm = args(2).sparse_bool_matrix_value ();
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	864 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	865 retval(2) = sbm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	866 retval(1) = scm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	867 retval(0) = sm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	868 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	869 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	870
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	871 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	872 @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	873
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	874 @node Accessing Global Variables in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	875 @subsection Accessing Global Variables in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	876
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	877 Global variables allow variables in the global scope to be accessed. Global
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	878 variables can be accessed within oct-files by using the support functions
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	879 @w{@code{get_global_value}} and @w{@code{set_global_value}}.
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	880 @w{@code{get_global_value}} takes two arguments, the first is a string
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	881 representing the variable name to obtain. The second argument is a boolean
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	882 argument specifying what to do if no global variable of the desired name is
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	883 found. 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	884
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	885 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	886 @EXAMPLEFILE(globaldemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	887 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	888
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	889 An example of its use is
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 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	892 @group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	893 global a b
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	894 b = 10;
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	895 globaldemo ("b")
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	896 @result{} 10
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	897 globaldemo ("c")
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	898 @result{} "Global variable not found"
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	899 num2str (a)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	900 @result{} 42
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	901 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	902 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	903
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	904 @node Calling Octave Functions from Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	905 @subsection Calling Octave Functions from Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	906
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	907 There is often a need to be able to call another Octave function from within an
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	908 oct-file, and there are many examples of such within Octave itself. For
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	909 example, the @code{quad} function is an oct-file that calculates the definite
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	910 integral by quadrature over a user-supplied function.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	911
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	912 There are also many ways in which a function could be given as input. It might
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	913 be passed as one of
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	914
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	915 @enumerate 1
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	916 @item Function Handle
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	917
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	918 @item Anonymous Function Handle
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	919
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	920 @item Inline Function
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	921
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	922 @item String
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	923 @end enumerate
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	924
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	925 The code below demonstrates all four methods of passing a function to an
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	926 oct-file.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	927
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	928 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	929 @EXAMPLEFILE(funcdemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	930 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	931
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	932 The first input to the demonstration code is a user-supplied function and the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	933 remaining arguments are all passed to the function.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	934
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	935 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	936 @group
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	937 funcdemo (@@sin, 1)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	938 @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	939 funcdemo (@@(x) sin (x), 1)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	940 @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	941 funcdemo (inline ("sin (x)"), 1)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	942 @result{} 0.84147
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	943 funcdemo ("sin", 1)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	944 @result{} 0.84147
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	945 funcdemo (@@atan2, 1, 1)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	946 @result{} 0.78540
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	947 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	948 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	949
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	950 When the user function is passed as a string the treatment of the function is
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	951 different. In some cases it is necessary to have the user supplied function as
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	952 an @code{octave_function} object. In that case the string argument can be used
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	953 to create a temporary function as demonstrated below.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	954
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	955 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	956 @group
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	957 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	958 std::string fcode = "function y = ";
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	959 fcode.append (fcn_name);
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	960 fcode.append ("(x) y = ");
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	961 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	962 fcode, "; endfunction");
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	963 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	964 if (fcn_name.length ())
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	965 clear_function (fcn_name);
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	966 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	967 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	968
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	969 There are two important things to know in this case. First, the number of
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	970 input arguments to the user function is fixed, and in the above example is a
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	971 single argument. Second, to avoid leaving the temporary function in the Octave
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	972 symbol table it should be cleared after use. Also, by convention all internal
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	973 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	974
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	975 @node Calling External Code from Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	976 @subsection Calling External Code from Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	977
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	978 Linking external C code to Octave is relatively simple, as the C functions can
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	979 easily be called directly from C++. One possible issue is that the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	980 declarations of the external C functions may need to be explicitly defined as C
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	981 functions to the compiler. If the declarations of the external C functions are
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	982 in the header @file{foo.h}, then the tactic to ensure that the C++ compiler
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	983 treats these declarations as C code is
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	984
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	985 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	986 @group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	987 #ifdef __cplusplus
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	988 extern "C"
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	989 @{
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	990 #endif
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	991 #include "foo.h"
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	992 #ifdef __cplusplus
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	993 @} /* end extern "C" */
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	994 #endif
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	995 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	996 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	997
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	998 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	999 differences in the manner in which compilers treat the linking of Fortran code
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1000 with C or C++ code. Octave supplies several macros that allow consistent
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1001 behavior across a number of compilers.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1002
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1003 The underlying Fortran code should use the @code{XSTOPX} function to replace
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1004 the Fortran @code{STOP} function. @code{XSTOPX} uses the Octave exception
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1005 handler to treat failing cases in the Fortran code explicitly. Note that
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1006 Octave supplies its own replacement @sc{blas} @code{XERBLA} function, which
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1007 uses @code{XSTOPX}.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1008
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1009 If the code calls @code{XSTOPX}, then the @w{@code{F77_XFCN}} macro should be
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1010 used to call the underlying Fortran function. The Fortran exception state can
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1011 then be checked with the global variable @code{f77_exception_encountered}. If
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1012 @code{XSTOPX} will not be called, then the @w{@code{F77_FCN}} macro should be
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1013 used instead to call the Fortran code.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1014
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1015 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	1016 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	1017 there is potentially an overhead in doing so. However, if @w{@code{F77_FCN}}
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1018 is used with code that calls @code{XSTOP}, Octave can generate a segmentation
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1019 fault.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1020
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1021 An example of the inclusion of a Fortran function in an oct-file is given in
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1022 the following example, where the C++ wrapper is
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1023
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1024 @example
18369 4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix. Rik <rik@octave.org> parents: 18367 diff changeset	1025 @EXAMPLEFILE(fortrandemo.cc)
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1026 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1027
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	1028 @noindent
10791 3140cb7a05a1 Add spellchecker scripts for Octave and run spellcheck of documentation Rik <octave@nomad.inbox5.com> parents: 9906 diff changeset	1029 and the Fortran function is
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1030
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1031 @example
18369 4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix. Rik <rik@octave.org> parents: 18367 diff changeset	1032 @EXAMPLEFILE(fortransub.f)
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1033 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1034
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1035 This example demonstrates most of the features needed to link to an external
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1036 Fortran function, including passing arrays and strings, as well as exception
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1037 handling. Both the Fortran and C++ files need to be compiled in order for the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1038 example to work.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1039
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1040 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1041 @group
18369 4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix. Rik <rik@octave.org> parents: 18367 diff changeset	1042 mkoctfile fortrandemo.cc fortransub.f
4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix. Rik <rik@octave.org> parents: 18367 diff changeset	1043 [b, s] = fortrandemo (1:3)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1044 @result{}
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1045 b = 1.00000 0.50000 0.33333
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1046 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	1047 [b, s] = fortrandemo (0:3)
4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix. Rik <rik@octave.org> parents: 18367 diff changeset	1048 error: fortrandemo: fortransub: divide by zero
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1049 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1050 @end example
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 @node Allocating Local Memory in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1053 @subsection Allocating Local Memory in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1054
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1055 Allocating memory within an oct-file might seem easy, as the C++ new/delete
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1056 operators can be used. However, in that case great care must be taken to avoid
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1057 memory leaks. The preferred manner in which to allocate memory for use locally
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1058 is to use the @w{@code{OCTAVE_LOCAL_BUFFER}} macro. An example of its use is
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1059
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1060 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1061 OCTAVE_LOCAL_BUFFER (double, tmp, len)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1062 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1063
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	1064 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1065 that returns a pointer @code{tmp} of type @code{double *} of length @code{len}.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1066
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1067 In this case, Octave itself will worry about reference counting and variable
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1068 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	1069
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1070 @node Input Parameter Checking in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1071 @subsection Input Parameter Checking in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1072
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1073 Because oct-files are compiled functions they open up the possibility of
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1074 crashing Octave through careless function calls or memory faults. It is quite
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1075 important that each and every function have a sufficient level of parameter
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1076 checking to ensure that Octave behaves well.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1077
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1078 The minimum requirement, as previously discussed, is to check the number of
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1079 input arguments before using them to avoid referencing a nonexistent argument.
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1080 However, in some cases this might not be sufficient as the underlying code
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1081 imposes further constraints. For example, an external function call might be
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1082 undefined if the input arguments are not integers, or if one of the arguments
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1083 is zero, or if the input is complex and a real value was expected. Therefore,
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1084 oct-files often need additional input parameter checking.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1085
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1086 There are several functions within Octave that can be useful for the purposes
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1087 of parameter checking. These include the methods of the @code{octave_value}
24987 a895967fd5a7 doc: grammarcheck manual (.txi) ahead of 4.4 release. Rik <rik@octave.org>* parents: 24534 diff changeset	1088 class like @code{is_real_matrix}, @code{is_numeric_type}, etc. (see
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1089 @file{ov.h}). Often, with a knowledge of the Octave m-file language, you can
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1090 guess at what the corresponding C++ routine will. In addition there are some
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1091 more specialized input validation functions of which a few are demonstrated
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1092 below.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1093
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1094 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1095 @EXAMPLEFILE(paramdemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1096 @end example
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1097
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1098 @noindent
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	1099 An example of its use is:
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1100
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1101 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1102 @group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1103 paramdemo ([1, 2, NaN, Inf])
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1104 @result{} Properties of input array:
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1105 includes Inf or NaN values
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1106 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	1107 includes only int, Inf or NaN values
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1108 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1109 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1110
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1111 @node Exception and Error Handling in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1112 @subsection Exception and Error Handling in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1113
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1114 Another important feature of Octave is its ability to react to the user typing
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1115 @key{Control-C} during extended calculations. This ability is based on the C++
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1116 exception handler, where memory allocated by the C++ new/delete methods is
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1117 automatically released when the exception is treated. When writing an oct-file
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1118 which may run for a long time the programmer must periodically use the macro
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1119 @w{@code{OCTAVE_QUIT}}, in order to allow Octave to check and possibly respond
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1120 to a user typing @key{Control-C}. For example:
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1121
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1122 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1123 @group
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1124 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	1125 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1126 OCTAVE_QUIT;
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1127 b.elem (i) = 2. * a.elem (i);
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1128 @}
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1129 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1130 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1131
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	1132 The presence of the @w{@code{OCTAVE_QUIT}} macro in the inner loop allows
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1133 Octave to detect and acknowledge a @key{Control-C} key sequence. Without this
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1134 macro, the user must either wait for the oct-file function to return before the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1135 interrupt is processed, or the user must press @key{Control-C} three times
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1136 which will force Octave to exit completely.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1137
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1138 The @w{@code{OCTAVE_QUIT}} macro does impose a very small performance penalty;
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1139 For loops that are known to be small it may 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	1140 @w{@code{OCTAVE_QUIT}}.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1141
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1142 When creating an oct-file that uses an external library, the function might
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1143 spend a significant portion of its time in the external library. It is not
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1144 generally possible to use the @w{@code{OCTAVE_QUIT}} macro in this case. The
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1145 alternative code in this case is
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1146
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1147 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1148 @group
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1149 BEGIN_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1150 @dots{} some code that calls a "foreign" function @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1151 END_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE;
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1152 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1153 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1154
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1155 The disadvantage of this is that if the foreign code allocates any memory
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1156 internally, then this memory might be lost during an interrupt, without being
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1157 deallocated. Therefore, ideally Octave itself should allocate any memory that
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1158 is needed by the foreign code, with either the @nospell{@code{fortran_vec}}
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1159 method or the @w{@code{OCTAVE_LOCAL_BUFFER}} macro.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1160
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1161 The Octave @code{unwind_protect} mechanism (@ref{The unwind_protect Statement})
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1162 can also be used in oct-files. In conjunction with the exception handling of
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1163 Octave, it ensures that certain recovery code is always run even if an
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1164 exception occurs. An example of the use of this mechanism is
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1165
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1166 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1167 @EXAMPLEFILE(unwinddemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1168 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1169
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	1170 As can be seen in the example:
6569 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 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1173 @group
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	1174 unwinddemo (1, 0)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1175 @result{} Inf
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1176 1 / 0
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1177 @result{} warning: division by zero
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1178 Inf
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1179 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1180 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1181
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1182 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	1183 @code{unwinddemo} function.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1184
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1185 @node Documentation and Testing of Oct-Files
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1186 @subsection Documentation and Testing of Oct-Files
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1187
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1188 The documentation for an oct-file is contained in the fourth string parameter
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1189 of the @w{@code{DEFUN_DLD}} macro. This string can be formatted in the same
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1190 manner as the help strings for user functions, however there are some issues
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1191 that are particular to the formatting of help strings within oct-files.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1192
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1193 The major issue is that the help string will typically be longer than a single
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1194 line of text, and so the formatting of long multi-line help strings needs to be
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1195 taken into account. There are several possible solutions, but the most common
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1196 is illustrated in the following example,
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1197
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1198 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1199 @group
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1200 DEFUN_DLD (do_what_i_want, args, nargout,
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1201 "-- texinfo --\n\
21319 8880d93010d8 Remove further uses of CLASS field in @deftypefn macro. Rik <rik@octave.org> parents: 21316 diff changeset	1202 @@deftypefn @{@} @{@} do_what_i_say (@@var@{n@})\n\
7081 503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	1203 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	1204 than what they requested.\n\
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1205 @@end deftypefn")
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1206 @{
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1207 @dots{}
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1208 @}
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1209 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1210 @end example
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 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1213 where each line of text is terminated by @code{\n\} which is an embedded
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1214 newline in the string together with a C++ string continuation character. Note
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1215 that the final @code{\} must be the last character on the line.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1216
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1217 Octave also includes the ability to embed test and demonstration code for a
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1218 function within the code itself (@pxref{Test and Demo Functions}). This can be
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1219 used from within oct-files (or in fact any file) with certain provisos. First,
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1220 the test and demo functions of Octave look for @code{%!} as the first two
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1221 characters of a line to identify test and demonstration code. This is a
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1222 requirement for oct-files as well. In addition, the test and demonstration
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1223 code must be wrapped in a comment block to avoid it being interpreted by the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1224 compiler. Finally, the Octave test and demonstration code must have access to
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1225 the original source code of the oct-file---not just the compiled code---as the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1226 tests are stripped 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	1227
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1228 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1229 @group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1230 /*
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1231 %!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	1232 %!error (sin ())
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1233 %!error (sin (1,1))
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1234 */
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1235 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1236 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1237
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1238 @c @node Application Programming Interface for Oct-Files
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1239 @c @subsection Application Programming Interface for Oct-Files
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1240 @c
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1241 @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	1242
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1243 @node Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1244 @section Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1245 @cindex mex-files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1246 @cindex mex
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1247
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1248 Octave includes an interface to allow legacy mex-files to be compiled and used
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1249 with Octave. This interface can also be used to share compiled code between
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1250 Octave and @sc{matlab} users. However, as mex-files expose @sc{matlab}'s
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1251 internal API, and the internal structure of Octave is different, a mex-file can
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1252 never have the same performance in Octave as the equivalent oct-file. In
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1253 particular, to support the manner in which variables are passed to mex
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1254 functions there are a significant number of additional copies of memory blocks
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1255 when invoking or returning from a mex-file function. For this reason, it is
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1256 recommended that any new code be written with the oct-file interface previously
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1257 discussed.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1258
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1259 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1260 * Getting Started with Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1261 * 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	1262 * Character Strings in Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1263 * Cell Arrays with Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1264 * Structures with Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1265 * Sparse Matrices with Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1266 * Calling Other Functions in Mex-Files::
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1267 @c * Application Programming Interface for Mex-Files::
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1268 @end menu
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1269
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1270 @node Getting Started with Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1271 @subsection Getting Started with Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1272
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1273 The basic command to build a mex-file is either @code{mkoctfile --mex} or
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1274 @code{mex}. The first command can be used either from within Octave or from
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1275 the command line. To avoid issues with @sc{matlab}'s own @code{mex} command,
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1276 the use of the command @code{mex} is limited to within Octave. Compiled
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1277 mex-files have the extension @file{.mex}.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1278
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1279 @DOCSTRING(mex)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1280
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1281 @DOCSTRING(mexext)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1282
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1283 Consider the following short example:
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1284
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1285 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1286 @group
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1287 @EXAMPLEFILE(myhello.c)
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1288 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1289 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1290
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1291 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	1292 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	1293 @sc{matlab} is that the header file @qcode{"matrix.h"} is implicitly included
22299 9fc91bb2aec3 doc: grammarcheck documentation for 4.2 release. Rik <rik@octave.org> parents: 21630 diff changeset	1294 through the inclusion of @qcode{"mex.h"}. This is necessary to avoid a
9fc91bb2aec3 doc: grammarcheck documentation for 4.2 release. Rik <rik@octave.org> parents: 21630 diff changeset	1295 conflict with the Octave file @qcode{"Matrix.h"} for operating systems and
9fc91bb2aec3 doc: grammarcheck documentation for 4.2 release. Rik <rik@octave.org> parents: 21630 diff changeset	1296 compilers that don't distinguish between filenames in upper and lower case.
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1297
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1298 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	1299 function takes four arguments:
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1300
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1301 @enumerate 1
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1302 @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	1303
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1304 @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	1305
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1306 @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	1307
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1308 @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	1309 @end enumerate
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1310
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1311 Note that the function name definition is not explicitly included in
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1312 @code{mexFunction} and so there can only be a single @code{mexFunction} entry
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1313 point per file. Instead, the name of the function as seen in Octave is
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1314 determined by the name of the mex-file itself minus the extension. If the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1315 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	1316
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1317 @example
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1318 mkoctfile --mex myhello.c
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1319 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1320
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1321 @noindent
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1322 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	1323 Octave as
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1324
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1325 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1326 @group
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1327 myhello (1,2,3)
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1328 @result{} Hello, World!
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1329 @result{} I have 3 inputs and 0 outputs
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1330 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1331 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1332
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1333 It should be noted that the mex-file contains no help string. To document
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1334 mex-files, there should exist an m-file in the same directory as the mex-file
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1335 itself. Taking the above as an example, there would need to be a file
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1336 @file{myhello.m} which might contain the text
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 %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	1340 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1341
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1342 In this case, the function that will be executed within Octave will be given by
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1343 the mex-file, while the help string will come from the m-file. This can also
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1344 be useful to allow a sample implementation of the mex-file within the Octave
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1345 language itself for testing purposes.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1346
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1347 Although there cannot be multiple entry points in a single mex-file, one can
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1348 use the @code{mexFunctionName} function to determine what name the mex-file was
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1349 called with. This can be used to alter the behavior of the mex-file based on
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1350 the function name. For example, if
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1351
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1352 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1353 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1354 @EXAMPLEFILE(myfunc.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1355 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1356 @end example
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1357
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1358 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1359 is in the file @file{myfunc.c}, and is compiled with
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1360
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1361 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1362 @group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1363 mkoctfile --mex myfunc.c
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1364 ln -s myfunc.mex myfunc2.mex
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1365 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1366 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1367
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1368 @noindent
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1369 then as can be seen by
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1370
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1371 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1372 @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	1373 myfunc ()
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1374 @result{} You called function: myfunc
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1375 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	1376 myfunc2 ()
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1377 @result{} You called function: myfunc2
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1378 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1379 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1380
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1381 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1382 the behavior of the mex-file can be altered depending on the function's name.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1383
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1384 Although the user should only include @file{mex.h} in their code, Octave
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1385 declares additional functions, typedefs, etc., available to the user to write
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1386 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	1387
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1388 @node Working with Matrices and Arrays in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1389 @subsection Working with Matrices and Arrays in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1390
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1391 The basic mex type of all variables is @code{mxArray}. Any object, such as a
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1392 matrix, cell array, or structure, is stored in this basic type. @code{mxArray}
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1393 serves essentially the same purpose as the @code{octave_value} class in
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1394 oct-files in that it acts as a container for all the more specialized types.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1395
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1396 The @code{mxArray} structure contains at a minimum, the name of the variable it
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1397 represents, its dimensions, its type, and whether the variable is real or
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1398 complex. It can also contain a number of additional fields depending on the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1399 type of the @code{mxArray}. There are a number of functions to create
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1400 @code{mxArray} structures, including @code{mxCreateDoubleMatrix},
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1401 @code{mxCreateCellArray}, @code{mxCreateSparse}, and the generic
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1402 @code{mxCreateNumericArray}.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1403
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1404 The basic function to access the data in an array is @code{mxGetPr}. Because
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1405 the mex interface assumes that real and imaginary parts of a complex array are
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1406 stored separately, there is an equivalent function @code{mxGetPi} that gets the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1407 imaginary part. Both of these functions are only for use with double precision
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1408 matrices. The generic functions @code{mxGetData} and @code{mxGetImagData}
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1409 perform the same operation for all matrix types. For example:
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1410
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1411 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1412 @group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1413 mxArray *m;
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1414 mwSize *dims;
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1415 UINT32_T *pr;
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1416
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1417 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	1418 dims[0] = 2; dims[1] = 2;
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1419 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	1420 pr = (UINT32_T *) mxGetData (m);
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1421 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1422 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1423
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1424 There are also the functions @code{mxSetPr}, etc., that perform the inverse,
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1425 and set the data of an array to use the block of memory pointed to by the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1426 argument of @code{mxSetPr}.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1427
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1428 Note the type @code{mwSize} used above, and also @code{mwIndex}, are defined as
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1429 the native precision of the indexing in Octave on the platform on which the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1430 mex-file is built. This allows both 32- and 64-bit platforms to support
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1431 mex-files. @code{mwSize} is used to define array dimensions and the maximum
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1432 number or elements, while @code{mwIndex} is used to define indexing into
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1433 arrays.
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1434
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1435 An example that demonstrates how to work with arbitrary real or complex double
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1436 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	1437
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1438 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1439 @EXAMPLEFILE(mypow2.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1440 @end example
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1441
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1442 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1443 An example of its use is
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1444
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1445 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1446 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1447 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	1448 all (b.^2 == mypow2 (b))
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1449 @result{} 1
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1450 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1451 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1452
7096 81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe] jwe parents: 7081 diff changeset	1453 The example above uses the functions @code{mxGetDimensions},
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1454 @code{mxGetNumberOfElements}, and @code{mxGetNumberOfDimensions} to work with
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1455 the dimensions of multi-dimensional arrays. The functions @code{mxGetM}, and
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1456 @code{mxGetN} are also available to find the number of rows and columns in a
23567 71bfd507663c doc: Periodic spellcheck of documentation. Rik <rik@octave.org> parents: 23565 diff changeset	1457 2-D matrix (@nospell{MxN} matrix).
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1458
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1459 @node Character Strings in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1460 @subsection Character Strings in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1461
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1462 As mex-files do not make the distinction between single and double quoted
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1463 strings that Octave does, there is perhaps less complexity in the use of
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1464 strings and character matrices. An example of their use that parallels the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1465 demo in @file{stringdemo.cc} is given in the file @file{mystring.c}, as shown
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1466 below.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1467
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1468 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1469 @EXAMPLEFILE(mystring.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1470 @end example
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1471
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1472 @noindent
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1473 An example of its expected output is
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1474
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1475 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1476 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1477 mystring (["First String"; "Second String"])
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1478 @result{} Second String
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1479 First String
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1480 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1481 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1482
7096 81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe] jwe parents: 7081 diff changeset	1483 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	1484 @code{mxCreateString}, @code{mxArrayToString}, and
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1485 @code{mxCreateCharMatrixFromStrings}. In a mex-file, a character string is
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1486 considered to be a vector rather than a matrix. This is perhaps an arbitrary
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1487 distinction as the data in the @code{mxArray} for the matrix is consecutive in
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1488 any case.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1489
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1490 @node Cell Arrays with Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1491 @subsection Cell Arrays with Mex-Files
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1492
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1493 One can perform exactly the same operations on Cell arrays in mex-files as in
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1494 oct-files. An example that duplicates the function of the @file{celldemo.cc}
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1495 oct-file in a mex-file is given by @file{mycell.c} as shown below.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1496
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1497 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1498 @EXAMPLEFILE(mycell.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1499 @end example
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1500
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1501 @noindent
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1502 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	1503
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1504 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1505 @group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1506 [b1, b2, b3] = mycell (@{1, [1, 2], "test"@})
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1507 @result{}
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1508 b1 = 1
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1509 b2 =
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1510
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1511 1 2
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1512
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1513 b3 = test
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1514 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1515 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1516
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1517 Note in the example the use of the @code{mxDuplicateArray} function. This is
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1518 needed as the @code{mxArray} pointer returned by @code{mxGetCell} might be
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1519 deallocated. The inverse function to @code{mxGetCell}, used for setting Cell
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1520 values, is @code{mxSetCell} and is defined as
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1521
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1522 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1523 void mxSetCell (mxArray ptr, int idx, mxArray val);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1524 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1525
7007 6304d9ea0a30 [project @ 2007-10-11 16:26:36 by jwe] jwe parents: 7001 diff changeset	1526 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	1527
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1528 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1529 @group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1530 mxArray mxCreateCellArray (int ndims, const int dims);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1531 mxArray *mxCreateCellMatrix (int m, int n);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1532 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1533 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1534
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	1535 @node Structures with Mex-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	1536 @subsection Structures with Mex-Files
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1537
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1538 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	1539 @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	1540 dimensional matrix, or @code{mxCreateStructArray}.
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1541
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1542 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1543 @group
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1544 mxArray mxCreateStructArray (int ndims, int dims,
446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1545 int num_keys,
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1546 const char **keys);
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1547 mxArray *mxCreateStructMatrix (int rows, int cols,
446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1548 int num_keys,
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1549 const char **keys);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1550 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1551 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1552
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1553 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	1554 @code{mxGetField} and @code{mxSetField} or alternatively with the
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1555 @code{mxGetFieldByNumber} and @code{mxSetFieldByNumber} functions.
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1556
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1557 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1558 @group
7081 503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	1559 mxArray mxGetField (const mxArray ptr, mwIndex index,
503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	1560 const char *key);
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1561 mxArray mxGetFieldByNumber (const mxArray ptr,
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1562 mwIndex index, int key_num);
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1563 void mxSetField (mxArray *ptr, mwIndex index,
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1564 const char key, mxArray val);
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1565 void mxSetFieldByNumber (mxArray *ptr, mwIndex index,
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1566 int key_num, mxArray *val);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1567 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1568 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1569
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1570 A difference between the oct-file interface to structures and the mex-file
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1571 version is that the functions to operate on structures in mex-files directly
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1572 include an @code{index} over the elements of the arrays of elements per
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1573 @code{field}; Whereas, the oct-file structure includes a Cell Array per field
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1574 of the structure.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1575
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1576 An example that demonstrates the use of structures in a mex-file can be found
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1577 in the file @file{mystruct.c} shown below.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1578
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1579 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1580 @EXAMPLEFILE(mystruct.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1581 @end example
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1582
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1583 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	1584
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1585 @example
18812 9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage. Rik <rik@octave.org> parents: 18797 diff changeset	1586 @group
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1587 a(1).f1 = "f11"; a(1).f2 = "f12";
7081 503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	1588 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	1589 b = mystruct (a);
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1590 @result{} field f1(0) = f11
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1591 field f1(1) = f21
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1592 field f2(0) = f12
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1593 field f2(1) = f22
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1594 b
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1595 @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	1596
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1597 this
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1598 that
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	1599
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1600 b(3)
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1601 @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	1602
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1603 this = this3
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1604 that = that3
18812 9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage. Rik <rik@octave.org> parents: 18797 diff changeset	1605 @end group
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1606 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1607
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1608 @node Sparse Matrices with Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1609 @subsection Sparse Matrices with Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1610
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1611 The Octave format for sparse matrices is identical to the mex format in that it
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1612 is a compressed column sparse format. Also, in both implementations sparse
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1613 matrices are required to be two-dimensional. The only difference of importance
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1614 to the programmer is that the real and imaginary parts of the matrix are stored
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1615 separately.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1616
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1617 The mex-file interface, in addition to using @code{mxGetM}, @code{mxGetN},
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1618 @code{mxSetM}, @code{mxSetN}, @code{mxGetPr}, @code{mxGetPi}, @code{mxSetPr},
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1619 and @code{mxSetPi}, also supplies the following functions.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1620
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1621 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1622 @group
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1623 mwIndex mxGetIr (const mxArray ptr);
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1624 mwIndex mxGetJc (const mxArray ptr);
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1625 mwSize mxGetNzmax (const mxArray *ptr);
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1626
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1627 void mxSetIr (mxArray ptr, mwIndex ir);
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1628 void mxSetJc (mxArray ptr, mwIndex jc);
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1629 void mxSetNzmax (mxArray *ptr, mwSize nzmax);
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1630 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1631 @end example
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1632
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1633 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1634 @code{mxGetNzmax} gets the maximum number of elements that can be stored in the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1635 sparse matrix. This is not necessarily the number of nonzero elements in the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1636 sparse matrix. @code{mxGetJc} returns an array with one additional value than
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1637 the number of columns in the sparse matrix. The difference between consecutive
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1638 values of the array returned by @code{mxGetJc} define the number of nonzero
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1639 elements in each column of the sparse matrix. Therefore,
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1640
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1641 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1642 @group
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1643 mwSize nz, n;
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1644 mwIndex *Jc;
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1645 mxArray *m;
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1646 @dots{}
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1647 n = mxGetN (m);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1648 Jc = mxGetJc (m);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1649 nz = Jc[n];
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1650 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1651 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1652
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1653 @noindent
18812 9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage. Rik <rik@octave.org> parents: 18797 diff changeset	1654 returns the actual number of nonzero elements stored in the matrix in
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1655 @code{nz}. As the arrays returned by @code{mxGetPr} and @code{mxGetPi} only
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1656 contain the nonzero values of the matrix, we also need a pointer to the rows of
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1657 the nonzero elements, and this is given by @code{mxGetIr}. A complete example
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1658 of the use of sparse matrices in mex-files is given by the file
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1659 @file{mysparse.c} shown below.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1660
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1661 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1662 @EXAMPLEFILE(mysparse.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1663 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1664
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1665 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	1666
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1667 @example
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1668 @group
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1669 sm = sparse ([1, 0; 0, pi]);
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1670 mysparse (sm)
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1671 @result{}
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1672 Matrix is 2-by-2 real sparse matrix with 2 elements
18812 9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage. Rik <rik@octave.org> parents: 18797 diff changeset	1673 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	1674 @end group
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1675 @end example
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1676
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1677 @node Calling Other Functions in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1678 @subsection Calling Other Functions in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1679
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1680 It is possible to call other Octave functions from within a mex-file using
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1681 @code{mexCallMATLAB}. An example of the use of @code{mexCallMATLAB} can be see
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1682 in the example below.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1683
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1684 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1685 @EXAMPLEFILE(myfeval.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1686 @end example
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1687
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1688 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	1689 @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	1690
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1691 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1692 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1693 a = myfeval ("sin", 1)
18367 d1e16bdb3958 myfeval.c: Fix segfault in mex example code. Rik <rik@octave.org> parents: 18358 diff changeset	1694 @result{} Starting file myfeval.mex
d1e16bdb3958 myfeval.c: Fix segfault in mex example code. Rik <rik@octave.org> parents: 18358 diff changeset	1695 I have 2 inputs and 1 outputs
d1e16bdb3958 myfeval.c: Fix segfault in mex example code. Rik <rik@octave.org> parents: 18358 diff changeset	1696 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	1697 a = 0.84147
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1698 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1699 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1700
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1701 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	1702 within a mex-file.
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1703
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1704 @c @node Application Programming Interface for Mex-Files
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1705 @c @subsection Application Programming Interface for Mex-Files
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1706 @c
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1707 @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	1708
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1709 @node Standalone Programs
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1710 @section Standalone Programs
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1711
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1712 The libraries Octave uses itself can be utilized in standalone applications.
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1713 These applications then have access, for example, to the array and matrix
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1714 classes, as well as to all of the Octave algorithms. The following C++
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1715 program, uses class Matrix from @file{liboctave.a} or @file{liboctave.so}.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1716
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1717 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1718 @EXAMPLEFILE(standalone.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1719 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1720
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1721 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1722 mkoctfile can be used to build a standalone application with a command like
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1723
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1724 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1725 @group
8097 804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1726 $ 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	1727 $ ./standalone
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1728 Hello Octave world!
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1729 11 12
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1730 21 22
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1731 $
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1732 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1733 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1734
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1735 Note that the application @code{standalone} will be dynamically linked against
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1736 the Octave libraries and any Octave support libraries. The above allows the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1737 Octave math libraries to be used by an application. It does not, however,
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1738 allow the script files, oct-files, or built-in functions of Octave to be used
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1739 by the application. To do that, the Octave interpreter needs to be initialized
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1740 first. An example of how to do this can then be seen in the code
8097 804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1741
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1742 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1743 @EXAMPLEFILE(embedded.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1744 @end example
8097 804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1745
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1746 @noindent
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1747 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	1748
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1749 @example
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1750 @group
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1751 $ mkoctfile --link-stand-alone embedded.cc -o embedded
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1752 $ ./embedded
16483 fcf1b0b52083 Use a better example of gcd() in embedded.cc Rik <rik@octave.org> parents: 16482 diff changeset	1753 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	1754 $
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1755 @end group
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1756 @end example
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1757
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1758 It is worth re-iterating that, if only built-in functions are to be called from
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1759 a C++ standalone program then it does not need to initialize the interpreter.
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1760 The general rule is that for a built-in function named @code{function_name} in
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1761 the interpreter, there will be a C++ function named @code{Ffunction_name} (note
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1762 the prepended capital @code{F}) accessible in the C++ API@. The declarations
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1763 for all built-in functions are collected in the header file
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1764 @code{builtin-defun-decls.h}. This feature should be used with care as the
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1765 list of built-in functions can change. No guarantees can be made that a
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1766 function that is currently a built-in won't be implemented as a .m file or as a
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1767 dynamically linked function in the future. An example of how to call built-in
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1768 functions from C++ can be seen in the code
17949 3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1769
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1770 @example
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1771 @EXAMPLEFILE(standalonebuiltin.cc)
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1772 @end example
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1773
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1774 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1775 which is compiled and run as a standalone application with
17949 3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1776
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1777 @example
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1778 @group
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1779 $ mkoctfile --link-stand-alone standalonebuiltin.cc -o standalonebuiltin
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1780 $ ./standalonebuiltin
17949 3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1781 This is a matrix:
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1782 11 12
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1783 21 22
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1784
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1785 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	1786 34.4952
18367 d1e16bdb3958 myfeval.c: Fix segfault in mex example code. Rik <rik@octave.org> parents: 18358 diff changeset	1787 $
17949 3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1788 @end group
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1789 @end example
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1790
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1791 @node Java Interface
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1792 @section Java Interface
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1793
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1794 @cindex using Octave with Java
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1795 @cindex Java, using with Octave
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1796 @cindex calling Java from Octave
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1797 @cindex Java, calling from Octave
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1798 @cindex calling Octave from Java
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1799 @cindex Octave, calling from Java
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1800
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1801 The Java Interface is designed for calling Java functions from within Octave.
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1802 If you want to do the reverse, and call Octave from within Java, try a library
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1803 like @code{javaOctave} (@url{https://kenai.com/projects/javaoctave/pages/Home})
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1804 or @code{joPas} (@url{http://jopas.sourceforge.net/}).
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1805
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1806 @menu
23213 b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1807 * Making Java Classes Available::
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1808 * How to use Java from within Octave::
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1809 * Passing parameters to the JVM::
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1810 * Java Interface Functions::
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1811 @end menu
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1812
23213 b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1813
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1814 @node Making Java Classes Available
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1815 @subsection Making Java Classes Available
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1816
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1817 @c - index -
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1818 @cindex classpath, setting
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1819 @cindex classpath, difference between static and dynamic
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1820 @cindex static classpath
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1821 @cindex dynamic classpath
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1822 @cindex @file{javaclasspath.txt}
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1823 @cindex @file{classpath.txt}
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1824 @cindex classes, making available to Octave
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1825 @c - index -
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1826
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1827 Java finds classes by searching a @var{classpath} which is a list of Java
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1828 archive files and/or directories containing class files. In Octave the
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1829 @var{classpath} is composed of two parts:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1830
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1831 @itemize
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1832 @item the @var{static classpath} is initialized once at startup of the JVM, and
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1833
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1834 @item the @var{dynamic classpath} which can be modified at runtime.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1835 @end itemize
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1836
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1837 Octave searches the @var{static classpath} first, and then the
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1838 @var{dynamic classpath}. Classes appearing in the @var{static classpath}, as
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1839 well as in the @var{dynamic classpath}, will therefore be found in the
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1840 @var{static classpath} and loaded from this location. Classes which will be
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1841 used frequently, or must be available to all users, should be added to the
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1842 @var{static classpath}. The @var{static classpath} is populated once from the
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1843 contents of a plain text file named @file{javaclasspath.txt} (or
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1844 @file{classpath.txt} historically) when the Java Virtual Machine starts. This
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1845 file contains one line for each individual classpath to be added to the
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1846 @var{static classpath}. These lines can identify directories containing class
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1847 files, or Java archives with complete class file hierarchies. Comment lines
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1848 starting with a @samp{#} or a @samp{%} character are ignored.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1849
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1850 The search rules for the file @file{javaclasspath.txt} (or
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1851 @file{classpath.txt}) are:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1852
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1853 @itemize
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1854 @item
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1855 First, Octave tries to locate it in the current directory (where Octave was
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1856 started from). If such a file is found, it is read and defines the initial
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1857 @var{static classpath}. Thus, it is possible to define a static classpath on a
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1858 'per Octave invocation' basis.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1859
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1860 @item
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1861 Next, Octave searches in the user's home directory. If a file
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1862 @file{javaclasspath.txt} exists here, its contents are appended to the static
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1863 classpath (if any). Thus, it is possible to build an initial static classpath
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1864 on a @nospell{'per user'} basis.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1865
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1866 @item
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1867 Finally, Octave looks for a @file{javaclasspath.txt} in the m-file directory
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1868 where Octave Java functions live. This is where the function
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1869 @file{javaclasspath.m} resides, usually something like
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1870 @file{@w{@env{OCTAVE_HOME}}/share/octave/@w{@env{OCTAVE_VERSION}}/m/java/}.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1871 You can find this directory by executing the command
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1872
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1873 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1874 which javaclasspath
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1875 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1876
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1877 If this file exists here, its contents are also appended to the
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1878 @var{static classpath}. Note that the archives and class directories defined
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1879 in this last step will affect all users.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1880 @end itemize
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1881
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1882 Classes which are used only by a specific script should be placed in the
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1883 @var{dynamic classpath}. This portion of the classpath can be modified at
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1884 runtime using the @code{javaaddpath} and @code{javarmpath} functions.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1885
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1886 Example:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1887
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1888 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1889 octave> base_path = "C:/Octave/java_files";
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1890
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1891 octave> # add two JAR archives to the dynamic classpath
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1892 octave> javaaddpath ([base_path, "/someclasses.jar"]);
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1893 octave> javaaddpath ([base_path, "/moreclasses.jar"]);
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1894
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1895 octave> # check the dynamic classpath
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1896 octave> p = javaclasspath;
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1897 octave> disp (p@{1@});
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1898 C:/Octave/java_files/someclasses.jar
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1899 octave> disp (p@{2@});
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1900 C:/Octave/java_files/moreclasses.jar
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1901
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1902 octave> # remove the first element from the classpath
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1903 octave> javarmpath ([base_path, "/someclasses.jar"]);
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1904 octave> p = javaclasspath;
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1905 octave> disp (p@{1@});
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1906 C:/Octave/java_files/moreclasses.jar
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1907
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1908 octave> # provoke an error
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1909 octave> disp (p@{2@});
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1910 error: A(I): Index exceeds matrix dimension.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1911 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1912
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1913 Another way to add files to the @var{dynamic classpath} exclusively for your
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1914 user account is to use the file @file{.octaverc} which is stored in your home
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1915 directory. All Octave commands in this file are executed each time you start a
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1916 new instance of Octave. The following example adds the directory @file{octave}
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1917 to Octave's search path and the archive @file{myclasses.jar} in this directory
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1918 to the Java search path.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1919
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1920 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1921 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1922 # contents of .octaverc:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1923 addpath ("~/octave");
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1924 javaaddpath ("~/octave/myclasses.jar");
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1925 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1926 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1927
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1928 @c ------------------------------------------------------------------------
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1929 @node How to use Java from within Octave
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1930 @subsection How to use Java from within Octave
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1931
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1932 The function @ref{XREFjavaObject,javaObject,javaObject} creates Java objects.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1933 In fact it invokes the public constructor of the class with the given name
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1934 and with the given parameters.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1935
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1936 The following example shows how to invoke the constructors
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1937 @code{BigDecimal(double)} and @code{BigDecimal(String)} of the builtin Java
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1938 class @code{java.math.BigDecimal}.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1939
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1940 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1941 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1942 javaObject ("java.math.BigDecimal", 1.001 );
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1943 javaObject ("java.math.BigDecimal", "1.001");
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1944 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1945 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1946
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1947 Note that parameters of the Octave type @code{double} are implicitly converted
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1948 into the Java type @code{double} and the Octave type (array of) @code{char} is
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1949 converted into the java type @code{String}. A Java object created by
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1950 @ref{XREFjavaObject,javaObject,javaObject} is never automatically converted
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1951 into an Octave type but remains a Java object. It can be assigned to an
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1952 Octave variable.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1953
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1954 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1955 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1956 a = 1.001;
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1957 b = javaObject ("java.math.BigDecimal", a);
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1958 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1959 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1960
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1961 Using @ref{XREFisjava,isjava,isjava}, it is possible to check whether a
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1962 variable is a Java object and its class can be determined as well. In
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1963 addition to the previous example:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1964
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1965 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1966 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1967 isjava (a)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1968 @result{} ans = 0
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1969 class (a)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1970 @result{} ans = double
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1971 isjava (b)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1972 @result{} ans = 1
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1973 class (b)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1974 @result{} ans = java.math.BigDecimal
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1975 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1976 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1977
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1978 The example above can be carried out using only Java objects:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1979
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1980 @example
23565 3a730821e4a2 doc: Peridoc grammarcheck of documentation. Rik <rik@octave.org> parents: 23220 diff changeset	1981 @group
23213 b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1982 a = javaObject ("java.lang.Double", 1.001);
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1983 b = javaObject ("java.math.BigDecimal", a);
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1984
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1985 isjava (a)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1986 @result{} ans = 1
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1987 class (a)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1988 @result{} ans = java.lang.Double
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1989 isjava (b)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1990 @result{} ans = 1
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1991 class (b)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1992 @result{} ans = java.math.BigDecimal
23565 3a730821e4a2 doc: Peridoc grammarcheck of documentation. Rik <rik@octave.org> parents: 23220 diff changeset	1993 @end group
23213 b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1994 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1995
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1996 One can see, that even a @code{java.lang.Double} is not converted to an Octave
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1997 @code{double}, when created by @ref{XREFjavaObject,javaObject,javaObject}.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1998 But ambiguities might arise, if the Java classes @code{java.lang.Double} or
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1999 @code{double} are parameters of a method (or a constructor). In this case
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2000 they can be converted into one another, depending on the context.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2001
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2002
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2003 Via @ref{XREFjavaObject,javaObject,javaObject} one may create all kinds of
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2004 Java objects but arrays. The latter are created through
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2005 @ref{XREFjavaArray,javaArray,javaArray}.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2006
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2007 It is possible to invoke public member methods on Java objects in Java syntax:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2008
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2009 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2010 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2011 a.toString
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2012 @result{} ans = 1.001
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2013 b.toString
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2014 @result{} ans = 1.000999999999999889865...
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2015 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2016 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2017
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2018 The second result may be surprising, but simply comes from the fact, that
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2019 @code{1.001} cannot exactly be represented as @code{double}, due to rounding.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2020 Note that unlike in Java, in Octave methods without arguments can be invoked
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2021 with and without parentheses @code{()}.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2022
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2023 Currently it is not possible to invoke static methods with a Java like syntax
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2024 from within Octave. Instead, one has to use the function
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2025 @ref{XREFjavaMethod,javaMethod,javaMethod} as in the following example:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2026
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2027 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2028 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2029 java.math.BigDecimal.valueOf(1.001); # does not work
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2030 javaMethod ("valueOf", "java.math.BigDecimal", 1.001); # workaround
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2031 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2032 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2033
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2034 As mentioned before, method and constructor parameters are converted
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2035 automatically between Octave and Java types, if appropriate. For functions
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2036 this is also true with return values, whereas for constructors this is not.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2037
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2038 It is also possible to access public fields of Java objects from within Octave
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2039 using Java syntax, with the limitation of static fields:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2040
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2041 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2042 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2043 java.math.BigDecimal.ONE; # does not work
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2044 java_get ("java.math.BigDecimal", "ONE"); # workaround
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2045 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2046 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2047
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2048 Accordingly, with @ref{XREFjava_set,java_set,java_set} the value of a field
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2049 can be set. Note that only public Java fields are accessible from within
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2050 Octave.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2051
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2052 The following example indicates that in Octave empty brackets @code{[]}
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2053 represent Java's @code{null} value and how Java exceptions are represented.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2054
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2055 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2056 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2057 javaObject ("java.math.BigDecimal", []);
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2058 @result{} error: [java] java.lang.NullPointerException
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2059 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2060 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2061
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2062 It is not recommended to represent Java's @code{null} value by empty brackets
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2063 @code{[]}, because @code{null} has no type whereas @code{[]} has type
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2064 @code{double}.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2065
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2066 In Octave it is possible to provide limited Java reflection by listing the
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2067 public fields and methods of a Java object, both static or not.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2068
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2069 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2070 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2071 fieldnames (<Java object>)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2072 methods (<Java object>)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2073 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2074 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2075
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2076 Finally, an examples is shown how to access the stack trace from within
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2077 Octave, where the function @ref{XREFdebug_java,debug_java,debug_java} is used
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2078 to set and to get the current debug state. In debug mode, the Java error and
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2079 the stack trace are displayed.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2080
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2081 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2082 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2083 debug_java (true) # use "false" to omit display of stack trace
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2084 debug_java ()
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2085 @result{} ans = 1
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2086 javaObject ("java.math.BigDecimal", "1") ...
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2087 .divide (javaObject ("java.math.BigDecimal", "0"))
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2088 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2089 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2090
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2091
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2092
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2093 @node Passing parameters to the JVM
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2094 @subsection Passing parameters to the JVM
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2095 @cindex memory, limitations on JVM
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2096
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2097 In order to execute Java code Octave creates a Java Virtual Machine (JVM).
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2098 Such a JVM allocates a fixed amount of initial memory and may expand this pool
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2099 up to a fixed maximum memory limit. The default values depend on the Java
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2100 version (@pxref{XREFjavamem,,javamem}). The memory pool is shared by all Java
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2101 objects running in the JVM@. This strict memory limit is intended mainly to
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2102 avoid runaway applications inside web browsers or in enterprise servers which
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2103 can consume all memory and crash the system. When the maximum memory limit is
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2104 hit, Java code will throw exceptions so that applications will fail or behave
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2105 unexpectedly.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2106
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2107 You can specify options for the creation of the JVM inside a file named
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2108 @file{java.opts}. This is a text file where enter you enter lines containing
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2109 @option{-X} and @option{-D} options that are then passed to the JVM during
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2110 initialization.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2111
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2112 The directory where the Java options file is located is specified by the
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2113 environment variable @w{@env{OCTAVE_JAVA_DIR}}. If unset the directory where
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2114 @file{javaclasspath.m} resides is used instead (typically
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2115 @file{@w{@env{OCTAVE_HOME}}/share/octave/@w{@env{OCTAVE_VERSION}}/m/java/}).
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2116 You can find this directory by executing
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2117
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2118 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2119 which javaclasspath
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2120 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2121
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2122 The @option{-X} options allow you to increase the maximum amount of memory
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2123 available to the JVM@. The following example allows up to 256 Megabytes to be
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2124 used by adding the following line to the @file{java.opts} file:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2125
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2126 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2127 -Xmx256m
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2128 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2129
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2130 The maximum possible amount of memory depends on your system. On a Windows
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2131 system with 2 Gigabytes main memory you should be able to set this maximum to
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2132 about 1 Gigabyte.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2133
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2134 If your application requires a large amount of memory from the beginning, you
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2135 can also specify the initial amount of memory allocated to the JVM@. Adding
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2136 the following line to the @file{java.opts} file starts the JVM with 64
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2137 Megabytes of initial memory:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2138
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2139 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2140 -Xms64m
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2141 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2142
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2143 For more details on the available @option{-X} options of your Java Virtual
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2144 Machine issue the command @samp{java -X} at the operating system command prompt
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2145 and consult the Java documentation.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2146
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2147 The @option{-D} options can be used to define system properties which can then
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2148 be used by Java classes inside Octave. System properties can be retrieved by
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2149 using the @code{getProperty()} methods of the @code{java.lang.System} class.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2150 The following example line defines the property @var{MyProperty} and assigns it
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2151 the string @code{12.34}.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2152
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2153 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2154 -DMyProperty=12.34
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2155 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2156
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2157 The value of this property can then be retrieved as a string by a Java object
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2158 or in Octave:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2159
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2160 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2161 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2162 octave> javaMethod ("getProperty", "java.lang.System", "MyProperty");
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2163 ans = 12.34
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2164 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2165 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2166
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2167 @seealso{javamem}
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2168
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2169
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2170
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2171 @node Java Interface Functions
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2172 @subsection Java Interface Functions
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2173
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2174 The following functions are the core of the Java Interface. They provide a way
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2175 to create a Java object, get and set its data fields, and call Java methods
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2176 which return results to Octave.
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2177
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2178 @cindex object, creating a Java object
23213 b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2179 @cindex instance, creating a Java instance
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2180 @DOCSTRING(javaObject)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2181
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2182 @cindex array, creating a Java array
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2183 @DOCSTRING(javaArray)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2184
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2185 There are many different variable types in Octave, but only ones created
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2186 through @code{javaObject} can use Java functions. Before using Java with an
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2187 unknown object the type can be checked with @code{isjava}.
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2188
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2189 @DOCSTRING(isjava)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2190
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2191 Once an object has been created it is natural to find out what fields the
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2192 object has, and to read (get) and write (set) them.
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2193
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2194 @cindex fields, displaying available fields of a Java object
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2195 In Octave the @code{fieldnames} function for structures has been overloaded
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2196 to return the fields of a Java object. For example:
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2197
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2198 @example
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2199 @group
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2200 dobj = javaObject ("java.lang.Double", pi);
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2201 fieldnames (dobj)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2202 @result{}
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2203 @{
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2204 [1,1] = public static final double java.lang.Double.POSITIVE_INFINITY
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2205 [1,2] = public static final double java.lang.Double.NEGATIVE_INFINITY
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2206 [1,3] = public static final double java.lang.Double.NaN
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2207 [1,4] = public static final double java.lang.Double.MAX_VALUE
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2208 [1,5] = public static final double java.lang.Double.MIN_NORMAL
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2209 [1,6] = public static final double java.lang.Double.MIN_VALUE
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2210 [1,7] = public static final int java.lang.Double.MAX_EXPONENT
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2211 [1,8] = public static final int java.lang.Double.MIN_EXPONENT
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2212 [1,9] = public static final int java.lang.Double.SIZE
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2213 [1,10] = public static final java.lang.Class java.lang.Double.TYPE
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2214 @}
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2215 @end group
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2216 @end example
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2217
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2218 @cindex field, returning value of Java object field
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2219 The analogy of objects with structures is carried over into reading and writing
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2220 object fields. To read a field the object is indexed with the @samp{.}
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2221 operator from structures. This is the preferred method for reading fields, but
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2222 Octave also provides a function interface to read fields with @code{java_get}.
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2223 An example of both styles is shown below.
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2224
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2225 @example
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2226 @group
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2227 dobj = javaObject ("java.lang.Double", pi);
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2228 dobj.MAX_VALUE
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2229 @result{} 1.7977e+308
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2230 java_get ("java.lang.Float", "MAX_VALUE")
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2231 @result{} 3.4028e+38
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2232 @end group
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2233 @end example
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2234
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2235 @DOCSTRING(java_get)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2236
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2237 @cindex field, setting value of Java object field
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2238 @DOCSTRING(java_set)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2239
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2240 @cindex methods, displaying available methods of a Java object
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2241 To see what functions can be called with an object use @code{methods}. For
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2242 example, using the previously created @var{dobj}:
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2243
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2244 @example
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2245 @group
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2246 methods (dobj)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2247 @result{}
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2248 Methods for class java.lang.Double:
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2249 boolean equals(java.lang.Object)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2250 java.lang.String toString(double)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2251 java.lang.String toString()
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2252 @dots{}
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2253 @end group
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2254 @end example
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2255
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2256 To call a method of an object the same structure indexing operator @samp{.} is
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2257 used. Octave also provides a functional interface to calling the methods of an
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2258 object through @code{javaMethod}. An example showing both styles is shown
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2259 below.
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2260
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2261 @example
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2262 @group
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2263 dobj = javaObject ("java.lang.Double", pi);
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2264 dobj.equals (3)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2265 @result{} 0
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2266 javaMethod ("equals", dobj, pi)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2267 @result{} 1
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2268 @end group
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2269 @end example
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2270
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2271 @cindex method, invoking a method of a Java object
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2272 @DOCSTRING(javaMethod)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2273
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2274 The following three functions are used to display and modify the class path
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2275 used by the Java Virtual Machine. This is entirely separate from Octave's
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2276 @env{PATH} variable and is used by the JVM to find the correct code to execute.
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2277
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2278 @cindex classpath, displaying
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2279 @cindex classpath, dynamic
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2280 @cindex dynamic classpath
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2281 @cindex classpath, static
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2282 @cindex static classpath
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2283 @DOCSTRING(javaclasspath)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2284
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2285 @findex javaaddpath
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2286 @cindex classpath, adding new path
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2287 @cindex path, adding to classpath
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2288 @cindex classpath, dynamic
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2289 @cindex dynamic classpath, adding new path
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2290 @DOCSTRING(javaaddpath)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2291
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2292 @cindex classpath, removing path
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2293 @cindex path, removing from classpath
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2294 @DOCSTRING(javarmpath)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2295
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2296 The following functions provide information and control over the interface
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2297 between Octave and the Java Virtual Machine.
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2298
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2299 @DOCSTRING(javachk)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2300
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2301 @DOCSTRING(usejava)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2302
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2303 @cindex memory, displaying Java memory status
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2304 @DOCSTRING(javamem)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2305
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2306 @DOCSTRING(java_matrix_autoconversion)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2307
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2308 @DOCSTRING(java_unsigned_autoconversion)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2309
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2310 @DOCSTRING(debug_java)

Mercurial > octave

annotate doc/interpreter/external.txi @ 25054:6652d3823428 stable