octave: doc/interpreter/external.txi annotate

annotate doc/interpreter/external.txi @ 31548:c8ad083a5802 stable

maint: Clean up m-files before Octave 8.1 release. * external.txi, oop.txi, Table.h, documentation.cc, gui-preferences-ed.h, lo-specfun.cc, range.tst : Eliminate triple newlines. * Map.m, MemoizedFunction.m, delaunayn.m, inputParser.m, __publish_latex_output__.m, publish.m, unpack.m, fminbnd.m, __add_default_menu__.m, gammainc.m, gallery.m, hadamard.m, weboptions.m: Add newline after keyword "function" or before keyword "endfunction" for readability. * getaudiodata.m, pkg.m : Add semicolon to end of line for error() statement. * movegui.m: Combine mutliple calls to set() into one for performance. * __unimplemented__.m (missing_functions): Remove missing functions that have been implemented. * __vectorize__.m, check_default_input.m, betaincinv.m, gammaincinv.m: Remove semicolon at end of line with "function" declaration. * weboptions.m: Remove semicolon at end of line with "if" keyword. * integrate_adaptive.m, factor.m: Use keyword "endif" rather than bare "end".

author	Rik <rik@octave.org>
date	Fri, 25 Nov 2022 21:23:54 -0800
parents	796f54d4ddbf
children	39b06d766f2a

rev	line source
30564 796f54d4ddbf update Octave Project Developers copyright for the new year John W. Eaton <jwe@octave.org> parents: 28713 diff changeset	1 @c Copyright (C) 2007-2022 The Octave Project Developers
7018 fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	2 @c
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	3 @c This file is part of Octave.
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	4 @c
24534 194eb4bd202b maint: Update punctuation for GPL v3 license text. Rik <rik@octave.org> parents: 23567 diff changeset	5 @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	6 @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	7 @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	8 @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	9 @c
22755 3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22482 diff changeset	10 @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	11 @c WITHOUT ANY WARRANTY; without even the implied warranty of
3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22482 diff changeset	12 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22482 diff changeset	13 @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	14 @c
7018 fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	15 @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	16 @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	17 @c <https://www.gnu.org/licenses/>.
6578 fbc16fe0e86a [project @ 2007-04-25 16:04:59 by jwe] jwe parents: 6577 diff changeset	18
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	19 @node External Code Interface
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	20 @appendix External Code Interface
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	21 @cindex dynamic-linking
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	22 @cindex Dynamically Linked Functions
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	23 @cindex Octave API
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	24
18953 bcbd309bf272 doc: Fix quote character at beginning of External Code Interfaces chapter. Rik <rik@octave.org> parents: 18797 diff changeset	25 "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	26
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	27 --- Ezra Pound
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	28
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	29 Octave is a fantastic language for solving many problems in science and
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	30 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	31 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	32 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	33 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	34 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	35 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	36 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	37
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	38 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	39 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	40 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	41 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	42 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	43 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	44 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	45 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	46 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	47 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	48 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	49
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	50 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	51 writing code outside of Octave.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	52
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	53 @itemize @bullet
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	54 @item
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	55 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	56
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	57 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	58 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	59 the outside code.
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	60
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	61 @item
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	62 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	63
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	64 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	65 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	66 (@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	67 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	68 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	69 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	70
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	71 @item
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	72 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	73 routines?
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	74
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	75 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	76 interpreted.
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	77
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	78 @item
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	79 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	80 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	81
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	82 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	83 inevitably be issues with tools such as compilers.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	84 @end itemize
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	85
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	86 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	87 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	88 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	89 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	90 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	91 develop.
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	92
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	93 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	94 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	95 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	96 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	97 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	98
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	99 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	100 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	101 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	102
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	103 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	104 * Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	105 * Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	106 * Standalone Programs::
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	107 * Java Interface::
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	108 @end menu
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	109
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	110 @node Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	111 @section Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	112 @cindex oct-files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	113 @cindex mkoctfile
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	114 @cindex oct
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	115
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	116 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	117 * Getting Started with Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	118 * Matrices and Arrays in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	119 * Character Strings in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	120 * Cell Arrays in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	121 * Structures in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	122 * Sparse Matrices in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	123 * Accessing Global Variables in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	124 * Calling Octave Functions from Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	125 * Calling External Code from Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	126 * Allocating Local Memory in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	127 * Input Parameter Checking in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	128 * 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	129 * 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	130 @c * Application Programming Interface for Oct-Files::
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	131 @end menu
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	132
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	133 @node Getting Started with Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	134 @subsection Getting Started with Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	135
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	136 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	137 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	138 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	139
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	140 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	141 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	142 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	143 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	144
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	145 @DOCSTRING(mkoctfile)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	146
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	147 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	148 C++ function that can be linked to Octave.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	149
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	150 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	151 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	152 @EXAMPLEFILE(helloworld.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	153 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	154 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	155
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	156 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	157 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	158 @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	159 in a C source file, nor any other language.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	160
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	161 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	162 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	163
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	164 @enumerate 1
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	165 @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	166
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	167 @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	168
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	169 @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	170 not used, and
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	171
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	172 @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	173 @end enumerate
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	174
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9080 diff changeset	175 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	176 @code{octave_value_list}.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	177
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	178 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	179 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	180 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	181 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	182 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	183 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	184 @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	185
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	186 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	187 mkoctfile helloworld.cc
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	188 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	189
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	190 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	191 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	192 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	193 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	194 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	195 @code{autoload} (@ref{Function Files}) function should be used.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	196
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	197 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	198 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	199 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	200
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	201 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	202 @group
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	203 helloworld (1, 2, 3)
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	204 @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	205 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	206 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	207
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	208 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	209 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	210 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	211 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	212 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	213 class.
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	214
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	215 @node Matrices and Arrays in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	216 @subsection Matrices and Arrays in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	217
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	218 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	219 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	220 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	221
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	222 @table @code
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	223 @item Matrix
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	224 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	225
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	226 @item ComplexMatrix
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	227 A complex matrix class defined in @file{CMatrix.h}
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	228
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	229 @item BoolMatrix
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	230 A boolean matrix class defined in @file{boolMatrix.h}
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	231 @end table
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	232
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	233 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	234 are a number of multi-dimensional array types including
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	235
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	236 @table @code
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	237 @item NDArray
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	238 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	239
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	240 @item ComplexNDarray
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	241 A complex array class defined in @file{CNDArray.h}
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	242
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	243 @item boolNDArray
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	244 A boolean array class defined in @file{boolNDArray.h}
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	245
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	246 @item int8NDArray
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	247 @itemx int16NDArray
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	248 @itemx int32NDArray
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	249 @itemx int64NDArray
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	250 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	251 @file{int8NDArray.h}, @file{int16NDArray.h}, etc.
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	252
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	253 @item uint8NDArray
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	254 @itemx uint16NDArray
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	255 @itemx uint32NDArray
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	256 @itemx uint64NDArray
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	257 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	258 @file{uint8NDArray.h}, @file{uint16NDArray.h}, etc.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	259 @end table
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	260
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	261 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	262 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	263
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	264 @itemize @bullet
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	265 @item
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	266 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	267
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	268 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	269 Matrix a;
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	270 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	271
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	272 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	273
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	274 @item
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	275 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	276 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	277
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	278 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	279 @group
20187 998881b6cdef external.txi: Fix example case for dim_vector (bug #45100). Piotr Held <pjheld@gmail.com> parents: 19721 diff changeset	280 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	281 Matrix a (dv);
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	282 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	283 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	284
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	285 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	286
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	287 @item
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	288 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	289
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	290 @example
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	291 Matrix a (2, 2)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	292 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	293
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	294 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	295 @end itemize
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	296
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	297 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	298 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	299 methods include
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	300
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	301 @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	302 @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	303 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	304 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	305 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	306 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	307 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	308 to get or set.
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	309 @end deftypefn
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	310
7001 8b0cfeb06365 [project @ 2007-10-10 18:02:59 by jwe] jwe parents: 6939 diff changeset	311 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	312 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	313 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	314
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	315 @deftypefn {Method} {octave_idx_type} numel (void) const
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	316 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	317 @end deftypefn
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	318
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	319 @deftypefn {Method} {size_t} byte_size (void) const
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	320 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	321 @end deftypefn
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	322
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	323 @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	324 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	325 @end deftypefn
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	326
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	327 @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	328 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	329 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	330 @end deftypefn
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	331
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	332 @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	333 @deftypefnx {Method} {void} resize (nrows, ncols)
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	334 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	335 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	336 of rows and columns in the matrix.
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	337 @end deftypefn
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	338
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	339 @deftypefn {Method} {T*} fortran_vec (void)
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	340 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	341 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	342 library.
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	343 @end deftypefn
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	344
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	345 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	346 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	347 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	348 @code{solve}, etc.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	349
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	350 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	351 @w{@code{DEFUN_DLD}} function is as follows
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	352
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	353 @example
21316 6cc091426e52 doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 20535 diff changeset	354 @group
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	355 @EXAMPLEFILE(addtwomatrices.cc)
21316 6cc091426e52 doc: Periodic grammarcheck of documentation. Rik <rik@octave.org> parents: 20535 diff changeset	356 @end group
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	357 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	358
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	359 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	360 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	361 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	362 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	363 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	364 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	365 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	366 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	367 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	368 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	369 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	370 catch the @code{octave_execution_error} exception.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	371
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	372 @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	373 @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	374 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	375
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	376 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	377 @group
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	378 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	379 @result{} 2 1
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	380 1 2
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	381 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	382 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	383
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	384 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	385 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	386 listed below.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	387
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	388 @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	389 @headitem Type @tab Function @tab Source Code
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	390 @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	391 @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	392 @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	393 @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	394 @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	395 @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	396 @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	397 @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	398 @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	399 @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	400 @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	401 @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	402 @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	403 @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	404 @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	405 @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	406 @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	407 @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	408 @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	409 @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	410 @end multitable
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	411
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	412 @node Character Strings in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	413 @subsection Character Strings in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	414
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	415 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	416 the example:
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	417
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	418 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	419 @EXAMPLEFILE(stringdemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	420 @end example
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	421
9080 ec41eabf4499 Cleanup documentation files dynamic.texi, testfun.texi, tips.texi Rik <rdrider0-list@yahoo.com> parents: 9038 diff changeset	422 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	423
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	424 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	425 @group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	426 s0 = ["First String"; "Second String"];
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	427 [s1,s2] = stringdemo (s0)
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	428 @result{} s1 = Second String
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	429 First String
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	430
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	431 @result{} s2 = First String
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	432 Second String
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	433
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	434 typeinfo (s2)
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	435 @result{} sq_string
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	436 typeinfo (s1)
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	437 @result{} string
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	438 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	439 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	440
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	441 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	442 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	443 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	444 below.
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	445
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	446 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	447 @group
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	448 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	449 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	450 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	451 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	452 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	453 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	454
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	455 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	456 @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	457 type of string should be specified. For example:
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	458
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	459 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	460 @group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	461 octave_value_list retval;
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	462 charNDArray ch;
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	463 @dots{}
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	464 // Create single quoted string
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	465 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	466 OR
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	467 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	468
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	469 // 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	470 retval(0) = octave_value (ch, '"');
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	471 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	472 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	473
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	474 @node Cell Arrays in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	475 @subsection Cell Arrays in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	476
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	477 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	478 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	479 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	480
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	481 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	482 @EXAMPLEFILE(celldemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	483 @end example
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	484
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	485 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	486 @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	487 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	488 them as individual output arguments. For example:
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	489
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	490 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	491 @group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	492 [b1, b2, b3] = celldemo (@{1, [1, 2], "test"@})
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	493 @result{}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	494 b1 = 1
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	495 b2 =
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	496
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	497 1 2
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 b3 = test
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	500 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	501 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	502
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	503 @node Structures in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	504 @subsection Structures in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	505
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	506 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	507 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	508 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	509
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	510 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	511
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	512 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	513 @EXAMPLEFILE(structdemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	514 @end example
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	515
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	516 An example of its use is
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 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	519 @group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	520 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	521 structdemo (x, "b")
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	522 @result{} selected = test
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	523 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	524 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	525
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	526 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	527 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	528 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	529 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	530 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	531 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	532
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	533 @example
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	534 octave_value tmp = arg0.contents (arg1)(0);
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	535 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	536
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	537 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	538 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	539 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	540 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	541
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	542 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	543 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	544 on just @code{contents}.
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	545
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	546 @node Sparse Matrices in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	547 @subsection Sparse Matrices in Oct-Files
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	548
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	549 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	550
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	551 @table @code
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	552 @item SparseMatrix
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	553 A double precision sparse matrix class
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	554
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	555 @item SparseComplexMatrix
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	556 A complex sparse matrix class
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	557
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	558 @item SparseBoolMatrix
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	559 A boolean sparse matrix class
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	560 @end table
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	561
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	562 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	563 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	564 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	565 @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	566
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	567 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	568 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	569 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	570 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	571 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	572 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	573 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	574 class than it is to the @code{NDArray} class.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	575
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	576 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	577 * Array and Sparse Class Differences::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	578 * Creating Sparse Matrices in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	579 * Using Sparse Matrices in Oct-Files::
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	580 @end menu
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	581
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	582 @node Array and Sparse Class Differences
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	583 @subsubsection Array and Sparse Class Differences
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	584
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	585 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	586 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	587
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	588 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	589 @group
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	590 SparseMatrix sm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	591 @dots{}
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	592 int nnz = sm.nelem ();
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	593 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	594 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	595
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	596 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	597 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	598 @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	599 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	600 @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	601 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	602 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	603 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	604 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	605 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	606 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	607 will not overflow.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	608
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	609 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	610 @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	611 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	612 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	613 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	614
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	615 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	616 @group
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	617 SparseMatrix sm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	618 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	619 for (int j = 0; j < nc; j++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	620 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	621 std::cerr << " (" << i << "," << j << "): " << sm(i,j) << "\n";
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	622 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	623 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	624
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	625 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	626 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	627 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	628 matrix.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	629
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	630 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	631 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	632 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	633 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	634 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	635 conversion, is
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	636
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	637 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	638 @group
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	639 SparseMatrix sm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	640 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	641 const SparseMatrix tmp (sm);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	642 for (int j = 0; j < nc; j++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	643 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	644 std::cerr << " (" << i << "," << j << "): " << tmp(i,j) << "\n";
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	645 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	646 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	647
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	648 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	649 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	650 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	651 @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	652 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	653 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	654 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	655 the matrix will become corrupted.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	656
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	657 @node Creating Sparse Matrices in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	658 @subsubsection Creating Sparse Matrices in Oct-Files
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	659
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	660 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	661 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	662 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	663 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	664 techniques have their advantages and disadvantages.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	665
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	666 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	667
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	668 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	669 @group
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	670 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	671 nz = 4, nr = 3, nc = 4;
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	672
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	673 ColumnVector ridx (nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	674 ColumnVector cidx (nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	675 ColumnVector data (nz);
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	676
18797 96f22d6674c4 Fix incorrect sparse matrix example code in oct-file chapter (bug #41799). Rik <rik@octave.org> parents: 18790 diff changeset	677 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	678 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	679 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	680 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	681 SparseMatrix sm (data, ridx, cidx, nr, nc);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	682 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	683 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	684
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	685 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	686 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	687 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	688 of the matrix itself, but is used internally.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	689
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	690 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	691 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	692 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	693 significantly speed up creation of the sparse matrix.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	694
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	695 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	696 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	697 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	698 matrix.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	699
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	700 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	701 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	702
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	703 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	704 @group
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	705 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	706 nz = 4, nr = 3, nc = 4;
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	707 SparseMatrix sm (nr, nc, nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	708 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	709 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	710 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	711
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	712 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	713 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	714 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	715 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	716 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	717 inserted; Only the column indices need to be updated.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	718
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	719 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	720 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	721 than are actually inserted in the matrix. Therefore,
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	722
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	723 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	724 @group
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	725 int nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	726 nr = 3, nc = 4;
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	727 SparseMatrix sm (nr, nc, 0);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	728 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	729 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	730 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	731
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	732 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	733 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	734 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	735 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	736 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	737 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	738 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	739 strictly needed.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	740
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	741 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	742 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	743 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	744 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	745 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	746 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	747 @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	748 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	749 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	750 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	751
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	752 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	753 @group
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	754 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	755 nz = 6, nr = 3, nc = 4;
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	756
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	757 SparseMatrix sm1 (nr, nc, nz);
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	758 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	759 sm1.maybe_compress (); // No zero elements were added
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	760
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	761 SparseMatrix sm2 (nr, nc, nz);
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	762 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	763 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	764 sm2.maybe_compress (true); // Zero elements were added
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	765 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	766 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	767
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	768 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	769 it will slow the creation of the matrix.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	770
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	771 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	772 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	773
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	774 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	775 octave_value arg;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	776 @dots{}
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	777 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	778 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	779 SparseMatrix sm (nr, nc, nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	780 Matrix m = arg.matrix_value ();
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	781
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	782 int ii = 0;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	783 sm.cidx (0) = 0;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	784 for (int j = 1; j < nc; j++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	785 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	786 for (int i = 0; i < nr; i++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	787 @{
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	788 double tmp = m(i,j);
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	789 if (tmp != 0.)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	790 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	791 sm.data(ii) = tmp;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	792 sm.ridx(ii) = i;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	793 ii++;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	794 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	795 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	796 sm.cidx(j+1) = ii;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	797 @}
18790 322eb69e30ad doc: Fix some Latin wording in documentation. Rik <rik@octave.org> parents: 18534 diff changeset	798 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	799 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	800
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	801 @noindent
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	802 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	803
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	804 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	805 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	806 @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	807 example would then be modified as
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	808
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	809 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	810 octave_value arg;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	811 @dots{}
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	812 int nz, nr, nc;
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	813 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	814 SparseMatrix sm (nr, nc, nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	815 Matrix m = arg.matrix_value ();
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	816
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	817 int ii = 0;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	818 sm.cidx (0) = 0;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	819 for (int j = 1; j < nc; j++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	820 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	821 for (int i = 0; i < nr; i++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	822 @{
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	823 double tmp = m(i,j);
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	824 if (tmp != 0.)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	825 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	826 if (ii == nz)
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 nz += 2; // Add 2 more elements
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	829 sm.change_capacity (nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	830 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	831 sm.data(ii) = tmp;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	832 sm.ridx(ii) = i;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	833 ii++;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	834 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	835 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	836 sm.cidx(j+1) = ii;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	837 @}
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	838 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	839 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	840
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	841 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	842 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	843 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	844 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	845 changing capacity.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	846
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	847 @node Using Sparse Matrices in Oct-Files
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	848 @subsubsection Using Sparse Matrices in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	849
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	850 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	851 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	852 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	853 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	854
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	855 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	856 @group
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	857 octave_value_list retval;
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	858
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	859 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	860 SparseComplexMatrix scm = args(1).sparse_complex_matrix_value ();
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	861 SparseBoolMatrix sbm = args(2).sparse_bool_matrix_value ();
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	862 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	863 retval(2) = sbm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	864 retval(1) = scm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	865 retval(0) = sm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	866 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	867 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	868
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	869 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	870 @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	871
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	872 @node Accessing Global Variables in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	873 @subsection Accessing Global Variables in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	874
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	875 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	876 variables can be accessed within oct-files by using the support functions
27595 18fea1c5b21a doc: improve example of using global variables from oct-files. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 26376 diff changeset	877 @w{@code{global_varval}} and @w{@code{global_assign}} from the current
18fea1c5b21a doc: improve example of using global variables from oct-files. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 26376 diff changeset	878 interpreter's symbol table. Both functions take as first argument a string
18fea1c5b21a doc: improve example of using global variables from oct-files. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 26376 diff changeset	879 representing the variable name to be obtained or assigned. The second
18fea1c5b21a doc: improve example of using global variables from oct-files. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 26376 diff changeset	880 argument of @w{@code{global_assign}} is the value to be assigned. An
18fea1c5b21a doc: improve example of using global variables from oct-files. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 26376 diff changeset	881 example of the use of these two functions is
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	882
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	883 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	884 @EXAMPLEFILE(globaldemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	885 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	886
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	887 An example of its use is
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 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	890 @group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	891 global a b
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	892 b = 10;
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	893 globaldemo ("b")
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	894 @result{} 10
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	895 globaldemo ("c")
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	896 @result{} "Global variable not found"
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	897 num2str (a)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	898 @result{} 42
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	899 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	900 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	901
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	902 @node Calling Octave Functions from Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	903 @subsection Calling Octave Functions from Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	904
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	905 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	906 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	907 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	908 integral by quadrature over a user-supplied function.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	909
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	910 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	911 be passed as one of
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	912
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	913 @enumerate 1
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	914 @item Function Handle
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	915
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	916 @item Anonymous 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 String
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	919 @end enumerate
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	920
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	921 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	922 oct-file.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	923
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	924 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	925 @EXAMPLEFILE(funcdemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	926 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	927
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	928 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	929 remaining arguments are all passed to the function.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	930
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	931 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	932 @group
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	933 funcdemo (@@sin, 1)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	934 @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	935 funcdemo (@@(x) sin (x), 1)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	936 @result{} 0.84147
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	939 funcdemo (@@atan2, 1, 1)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	940 @result{} 0.78540
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	941 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	942 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	943
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	944 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	945 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	946 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	947 to create a temporary function as demonstrated below.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	948
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	949 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	950 @group
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	951 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	952 std::string fcode = "function y = ";
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	953 fcode.append (fcn_name);
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	954 fcode.append ("(x) y = ");
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	955 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	956 fcode, "; endfunction");
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	957 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	958 if (fcn_name.length ())
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	959 clear_function (fcn_name);
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	960 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	961 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	962
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	963 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	964 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	965 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	966 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	967 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	968
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	969 @node Calling External Code from Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	970 @subsection Calling External Code from Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	971
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	972 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	973 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	974 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	975 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	976 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	977 treats these declarations as C code is
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	978
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	979 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	980 @group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	981 #ifdef __cplusplus
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	982 extern "C"
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	983 @{
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	984 #endif
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	985 #include "foo.h"
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	986 #ifdef __cplusplus
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	987 @} /* end extern "C" */
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	988 #endif
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	989 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	990 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	991
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	992 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	993 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	994 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	995 behavior across a number of compilers.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	996
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	997 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	998 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	999 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	1000 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	1001 uses @code{XSTOPX}.
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 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	1004 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	1005 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	1006 @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	1007 used instead to call the Fortran code.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1008
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1009 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	1010 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	1011 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	1012 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	1013 fault.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1014
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1015 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	1016 the following example, where the C++ wrapper is
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1017
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1018 @example
18369 4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix. Rik <rik@octave.org> parents: 18367 diff changeset	1019 @EXAMPLEFILE(fortrandemo.cc)
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1020 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1021
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	1022 @noindent
10791 3140cb7a05a1 Add spellchecker scripts for Octave and run spellcheck of documentation Rik <octave@nomad.inbox5.com> parents: 9906 diff changeset	1023 and the Fortran function is
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1024
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1025 @example
18369 4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix. Rik <rik@octave.org> parents: 18367 diff changeset	1026 @EXAMPLEFILE(fortransub.f)
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1027 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1028
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1029 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	1030 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	1031 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	1032 example to work.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1033
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1034 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1035 @group
18369 4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix. Rik <rik@octave.org> parents: 18367 diff changeset	1036 mkoctfile fortrandemo.cc fortransub.f
4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix. Rik <rik@octave.org> parents: 18367 diff changeset	1037 [b, s] = fortrandemo (1:3)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1038 @result{}
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1039 b = 1.00000 0.50000 0.33333
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1040 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	1041 [b, s] = fortrandemo (0:3)
4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix. Rik <rik@octave.org> parents: 18367 diff changeset	1042 error: fortrandemo: fortransub: divide by zero
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1043 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1044 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1045
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1046 @node Allocating Local Memory in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1047 @subsection Allocating Local Memory in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1048
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1049 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	1050 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	1051 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	1052 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	1053
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1054 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1055 OCTAVE_LOCAL_BUFFER (double, tmp, len)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1056 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1057
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	1058 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1059 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	1060
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1061 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	1062 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	1063
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1064 @node Input Parameter Checking in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1065 @subsection Input Parameter Checking in Oct-Files
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 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	1068 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	1069 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	1070 checking to ensure that Octave behaves well.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1071
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1072 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	1073 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	1074 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	1075 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	1076 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	1077 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	1078 oct-files often need additional input parameter checking.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1079
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1080 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	1081 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	1082 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	1083 @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	1084 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	1085 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	1086 below.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1087
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1088 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1089 @EXAMPLEFILE(paramdemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1090 @end example
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1091
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1092 @noindent
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	1093 An example of its use is:
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1094
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1095 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1096 @group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1097 paramdemo ([1, 2, NaN, Inf])
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1098 @result{} Properties of input array:
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1099 includes Inf or NaN values
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1100 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	1101 includes only int, Inf or NaN values
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1102 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1103 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1104
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1105 @node Exception and Error Handling in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1106 @subsection Exception and Error Handling in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1107
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1108 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	1109 @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	1110 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	1111 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	1112 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	1113 @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	1114 to a user typing @key{Control-C}. For example:
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1115
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1116 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1117 @group
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1118 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	1119 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1120 OCTAVE_QUIT;
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1121 b.elem (i) = 2. * a.elem (i);
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1122 @}
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1123 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1124 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1125
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	1126 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	1127 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	1128 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	1129 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	1130 which will force Octave to exit completely.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1131
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1132 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	1133 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	1134 @w{@code{OCTAVE_QUIT}}.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1135
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1136 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	1137 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	1138 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	1139 alternative code in this case is
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1140
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1141 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1142 @group
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1143 BEGIN_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1144 @dots{} some code that calls a "foreign" function @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1145 END_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE;
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1146 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1147 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1148
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1149 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	1150 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	1151 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	1152 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	1153 method or the @w{@code{OCTAVE_LOCAL_BUFFER}} macro.
6569 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 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	1156 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	1157 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	1158 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	1159
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1160 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1161 @EXAMPLEFILE(unwinddemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1162 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1163
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	1164 As can be seen in the example:
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1165
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1166 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1167 @group
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	1168 unwinddemo (1, 0)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1169 @result{} Inf
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1170 1 / 0
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1171 @result{} warning: division by zero
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1172 Inf
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1173 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1174 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1175
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1176 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	1177 @code{unwinddemo} function.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1178
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1179 @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	1180 @subsection Documentation and Testing of Oct-Files
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1181
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1182 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	1183 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	1184 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	1185 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	1186
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1187 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	1188 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	1189 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	1190 is illustrated in the following example,
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1191
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1192 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1193 @group
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1194 DEFUN_DLD (do_what_i_want, args, nargout,
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1195 "-- texinfo --\n\
21319 8880d93010d8 Remove further uses of CLASS field in @deftypefn macro. Rik <rik@octave.org> parents: 21316 diff changeset	1196 @@deftypefn @{@} @{@} do_what_i_say (@@var@{n@})\n\
7081 503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	1197 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	1198 than what they requested.\n\
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1199 @@end deftypefn")
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1200 @{
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1201 @dots{}
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1202 @}
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1203 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1204 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1205
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1206 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1207 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	1208 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	1209 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	1210
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1211 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	1212 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	1213 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	1214 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	1215 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	1216 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	1217 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	1218 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	1219 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	1220 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	1221
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1222 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1223 @group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1224 /*
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1225 %!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	1226 %!error (sin ())
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1227 %!error (sin (1,1))
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1228 */
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1229 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1230 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1231
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1232 @c @node Application Programming Interface for Oct-Files
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1233 @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	1234 @c
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1235 @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	1236
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1237 @node Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1238 @section Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1239 @cindex mex-files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1240 @cindex mex
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1241
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1242 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	1243 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	1244 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	1245 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	1246 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	1247 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	1248 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	1249 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	1250 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	1251 discussed.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1252
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1253 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1254 * Getting Started with Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1255 * 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	1256 * Character Strings in Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1257 * Cell Arrays with Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1258 * Structures with Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1259 * Sparse Matrices with Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1260 * 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	1261 @c * Application Programming Interface for Mex-Files::
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1262 @end menu
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1263
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1264 @node Getting Started with Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1265 @subsection Getting Started with Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1266
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1267 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	1268 @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	1269 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	1270 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	1271 mex-files have the extension @file{.mex}.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1272
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1273 @DOCSTRING(mex)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1274
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1275 @DOCSTRING(mexext)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1276
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1277 Consider the following short example:
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1278
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1279 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1280 @group
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1281 @EXAMPLEFILE(myhello.c)
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1282 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1283 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1284
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1285 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	1286 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	1287 @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	1288 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	1289 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	1290 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	1291
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1292 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	1293 function takes four arguments:
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1294
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1295 @enumerate 1
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1296 @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	1297
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1298 @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	1299
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1300 @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	1301
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1302 @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	1303 @end enumerate
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1304
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1305 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	1306 @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	1307 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	1308 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	1309 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	1310
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1311 @example
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1312 mkoctfile --mex myhello.c
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1313 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1314
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1315 @noindent
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1316 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	1317 Octave as
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1318
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1319 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1320 @group
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1321 myhello (1,2,3)
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1322 @result{} Hello, World!
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1323 @result{} I have 3 inputs and 0 outputs
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1324 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1325 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1326
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1327 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	1328 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	1329 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	1330 @file{myhello.m} which might contain the text
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1331
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1332 @example
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1333 %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	1334 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1335
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1336 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	1337 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	1338 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	1339 language itself for testing purposes.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1340
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1341 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	1342 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	1343 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	1344 the function name. For example, if
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1345
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1346 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1347 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1348 @EXAMPLEFILE(myfunc.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1349 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1350 @end example
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1351
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1352 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1353 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	1354
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1355 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1356 @group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1357 mkoctfile --mex myfunc.c
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1358 ln -s myfunc.mex myfunc2.mex
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1359 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1360 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1361
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1362 @noindent
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1363 then as can be seen by
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1364
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1365 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1366 @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	1367 myfunc ()
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1368 @result{} You called function: myfunc
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1369 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	1370 myfunc2 ()
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1371 @result{} You called function: myfunc2
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1372 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1373 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1374
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1375 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1376 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	1377
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1378 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	1379 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	1380 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	1381
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1382 @node Working with Matrices and Arrays in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1383 @subsection Working with Matrices and Arrays in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1384
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1385 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	1386 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	1387 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	1388 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	1389
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1390 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	1391 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	1392 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	1393 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	1394 @code{mxArray} structures, including @code{mxCreateDoubleMatrix},
cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1395 @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	1396 @code{mxCreateNumericArray}.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1397
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1398 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	1399 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	1400 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	1401 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	1402 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	1403 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	1404
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1405 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1406 @group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1407 mxArray *m;
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1408 mwSize *dims;
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1409 UINT32_T *pr;
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1410
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1411 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	1412 dims[0] = 2; dims[1] = 2;
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1413 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	1414 pr = (UINT32_T *) mxGetData (m);
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1415 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1416 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1417
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1418 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	1419 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	1420 argument of @code{mxSetPr}.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1421
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1422 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	1423 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	1424 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	1425 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	1426 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	1427 arrays.
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1428
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1429 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	1430 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	1431
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1432 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1433 @EXAMPLEFILE(mypow2.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1434 @end example
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1435
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1436 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1437 An example of its use is
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1438
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1439 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1440 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1441 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	1442 all (b.^2 == mypow2 (b))
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1443 @result{} 1
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1444 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1445 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1446
7096 81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe] jwe parents: 7081 diff changeset	1447 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	1448 @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	1449 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	1450 @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	1451 2-D matrix (@nospell{MxN} matrix).
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1452
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1453 @node Character Strings in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1454 @subsection Character Strings in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1455
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1456 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	1457 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	1458 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	1459 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	1460 below.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1461
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1462 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1463 @EXAMPLEFILE(mystring.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1464 @end example
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1465
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1466 @noindent
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1467 An example of its expected output is
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1468
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1469 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1470 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1471 mystring (["First String"; "Second String"])
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1472 @result{} Second String
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1473 First String
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1474 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1475 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1476
7096 81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe] jwe parents: 7081 diff changeset	1477 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	1478 @code{mxCreateString}, @code{mxArrayToString}, and
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1479 @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	1480 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	1481 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	1482 any case.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1483
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1484 @node Cell Arrays with Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1485 @subsection Cell Arrays with Mex-Files
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1486
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1487 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	1488 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	1489 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	1490
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1491 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1492 @EXAMPLEFILE(mycell.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1493 @end example
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1494
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1495 @noindent
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1496 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	1497
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1498 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1499 @group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1500 [b1, b2, b3] = mycell (@{1, [1, 2], "test"@})
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1501 @result{}
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1502 b1 = 1
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1503 b2 =
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1504
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1505 1 2
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1506
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1507 b3 = test
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1508 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1509 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1510
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1511 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	1512 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	1513 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	1514 values, is @code{mxSetCell} and is defined as
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1515
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1516 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1517 void mxSetCell (mxArray ptr, int idx, mxArray val);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1518 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1519
7007 6304d9ea0a30 [project @ 2007-10-11 16:26:36 by jwe] jwe parents: 7001 diff changeset	1520 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	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 @group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1524 mxArray mxCreateCellArray (int ndims, const int dims);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1525 mxArray *mxCreateCellMatrix (int m, int n);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1526 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1527 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1528
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	1529 @node Structures with Mex-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	1530 @subsection Structures with Mex-Files
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1531
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1532 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	1533 @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	1534 dimensional matrix, or @code{mxCreateStructArray}.
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1535
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1536 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1537 @group
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1538 mxArray mxCreateStructArray (int ndims, int dims,
446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1539 int num_keys,
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1540 const char **keys);
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1541 mxArray *mxCreateStructMatrix (int rows, int cols,
446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1542 int num_keys,
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1543 const char **keys);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1544 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1545 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1546
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1547 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	1548 @code{mxGetField} and @code{mxSetField} or alternatively with the
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1549 @code{mxGetFieldByNumber} and @code{mxSetFieldByNumber} functions.
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1550
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1551 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1552 @group
7081 503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	1553 mxArray mxGetField (const mxArray ptr, mwIndex index,
503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	1554 const char *key);
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1555 mxArray mxGetFieldByNumber (const mxArray ptr,
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1556 mwIndex index, int key_num);
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1557 void mxSetField (mxArray *ptr, mwIndex index,
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1558 const char key, mxArray val);
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1559 void mxSetFieldByNumber (mxArray *ptr, mwIndex index,
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1560 int key_num, mxArray *val);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1561 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1562 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1563
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1564 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	1565 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	1566 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	1567 @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	1568 of the structure.
6593 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 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	1571 in the file @file{mystruct.c} shown below.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1572
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1573 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1574 @EXAMPLEFILE(mystruct.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1575 @end example
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1576
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1577 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	1578
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1579 @example
18812 9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage. Rik <rik@octave.org> parents: 18797 diff changeset	1580 @group
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18953 diff changeset	1581 a(1).f1 = "f11"; a(1).f2 = "f12";
7081 503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	1582 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	1583 b = mystruct (a);
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1584 @result{} field f1(0) = f11
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1585 field f1(1) = f21
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1586 field f2(0) = f12
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1587 field f2(1) = f22
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1588 b
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1589 @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	1590
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1591 this
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1592 that
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	1593
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1594 b(3)
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1595 @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	1596
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1597 this = this3
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1598 that = that3
18812 9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage. Rik <rik@octave.org> parents: 18797 diff changeset	1599 @end group
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1600 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1601
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1602 @node Sparse Matrices with Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1603 @subsection Sparse Matrices with Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1604
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1605 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	1606 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	1607 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	1608 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	1609 separately.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1610
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1611 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	1612 @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	1613 and @code{mxSetPi}, also supplies the following functions.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1614
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1615 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1616 @group
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1617 mwIndex mxGetIr (const mxArray ptr);
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1618 mwIndex mxGetJc (const mxArray ptr);
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1619 mwSize mxGetNzmax (const mxArray *ptr);
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1620
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1621 void mxSetIr (mxArray ptr, mwIndex ir);
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1622 void mxSetJc (mxArray ptr, mwIndex jc);
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1623 void mxSetNzmax (mxArray *ptr, mwSize nzmax);
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1624 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1625 @end example
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1626
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1627 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1628 @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	1629 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	1630 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	1631 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	1632 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	1633 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	1634
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1635 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1636 @group
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1637 mwSize nz, n;
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1638 mwIndex *Jc;
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1639 mxArray *m;
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1640 @dots{}
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1641 n = mxGetN (m);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1642 Jc = mxGetJc (m);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1643 nz = Jc[n];
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1644 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1645 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1646
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1647 @noindent
18812 9ac2357f19bc doc: Replace "non-zero" with "nonzero" to match existing usage. Rik <rik@octave.org> parents: 18797 diff changeset	1648 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	1649 @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	1650 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	1651 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	1652 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	1653 @file{mysparse.c} shown below.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1654
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1655 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1656 @EXAMPLEFILE(mysparse.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1657 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1658
18358 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1659 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	1660
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1661 @example
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1662 @group
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1663 sm = sparse ([1, 0; 0, pi]);
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1664 mysparse (sm)
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1665 @result{}
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1666 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	1667 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	1668 @end group
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1669 @end example
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1670
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1671 @node Calling Other Functions in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1672 @subsection Calling Other Functions in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1673
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1674 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	1675 @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	1676 in the example below.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1677
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1678 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1679 @EXAMPLEFILE(myfeval.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1680 @end example
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1681
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1682 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	1683 @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	1684
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1685 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1686 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1687 a = myfeval ("sin", 1)
18367 d1e16bdb3958 myfeval.c: Fix segfault in mex example code. Rik <rik@octave.org> parents: 18358 diff changeset	1688 @result{} Starting file myfeval.mex
d1e16bdb3958 myfeval.c: Fix segfault in mex example code. Rik <rik@octave.org> parents: 18358 diff changeset	1689 I have 2 inputs and 1 outputs
d1e16bdb3958 myfeval.c: Fix segfault in mex example code. Rik <rik@octave.org> parents: 18358 diff changeset	1690 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	1691 a = 0.84147
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1692 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1693 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1694
28427 7a8c69c4eb55 convert obsolete octave_fcn_inline object to @inline class John W. Eaton <jwe@octave.org> parents: 27595 diff changeset	1695 Note that it is not possible to use function handles within a mex-file.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1696
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1697 @c @node Application Programming Interface for Mex-Files
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1698 @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	1699 @c
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1700 @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	1701
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1702 @node Standalone Programs
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1703 @section Standalone Programs
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1704
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1705 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	1706 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	1707 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	1708 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	1709
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1710 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1711 @EXAMPLEFILE(standalone.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1712 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1713
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1714 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1715 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	1716
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1717 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1718 @group
8097 804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1719 $ 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	1720 $ ./standalone
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1721 Hello Octave world!
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1722 11 12
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1723 21 22
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1724 $
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1725 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1726 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1727
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1728 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	1729 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	1730 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	1731 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	1732 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	1733 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	1734
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1735 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1736 @EXAMPLEFILE(embedded.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1737 @end example
8097 804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1738
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1739 @noindent
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1740 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	1741
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1742 @example
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1743 @group
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1744 $ 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	1745 $ ./embedded
16483 fcf1b0b52083 Use a better example of gcd() in embedded.cc Rik <rik@octave.org> parents: 16482 diff changeset	1746 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	1747 $
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1748 @end group
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1749 @end example
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1750
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1751 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	1752 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	1753 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	1754 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	1755 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	1756 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	1757 @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	1758 list of built-in functions can change. No guarantees can be made that a
28713 28d2511f2af2 maint: grammarcheck documentation ahead of 6.1 release. Rik <rik@octave.org> parents: 28427 diff changeset	1759 function that is currently a built-in won't be implemented as a @file{.m} file
28d2511f2af2 maint: grammarcheck documentation ahead of 6.1 release. Rik <rik@octave.org> parents: 28427 diff changeset	1760 or as a dynamically linked function in the future. An example of how to call
28d2511f2af2 maint: grammarcheck documentation ahead of 6.1 release. Rik <rik@octave.org> parents: 28427 diff changeset	1761 built-in 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	1762
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1763 @example
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1764 @EXAMPLEFILE(standalonebuiltin.cc)
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1765 @end example
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1766
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1767 @noindent
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	1768 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	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 @group
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1772 $ 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	1773 $ ./standalonebuiltin
17949 3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1774 This is a matrix:
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1775 11 12
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1776 21 22
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1777
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1778 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	1779 34.4952
18367 d1e16bdb3958 myfeval.c: Fix segfault in mex example code. Rik <rik@octave.org> parents: 18358 diff changeset	1780 $
17949 3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1781 @end group
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1782 @end example
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1783
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1784 @node Java Interface
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1785 @section Java Interface
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1786
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1787 @cindex using Octave with Java
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1788 @cindex Java, using with Octave
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1789 @cindex calling Java from Octave
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1790 @cindex Java, calling from Octave
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1791 @cindex calling Octave from Java
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1792 @cindex Octave, calling from Java
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 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	1795 If you want to do the reverse, and call Octave from within Java, try a library
25143 13fd0610480f doc: Use https whenever possible in @url entries. Rik <rik@octave.org> parents: 25054 diff changeset	1796 like @code{joPas} (@url{http://jopas.sourceforge.net}).
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1797
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1798 @menu
23213 b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1799 * Making Java Classes Available::
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1800 * How to use Java from within Octave::
25816 98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	1801 * Set up the JVM::
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1802 * Java Interface Functions::
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1803 @end menu
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	1804
23213 b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1805
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1806 @node Making Java Classes Available
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1807 @subsection Making Java Classes Available
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1808
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1809 @c - index -
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1810 @cindex classpath, setting
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1811 @cindex classpath, difference between static and dynamic
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1812 @cindex static classpath
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1813 @cindex dynamic classpath
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1814 @cindex @file{javaclasspath.txt}
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1815 @cindex @file{classpath.txt}
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1816 @cindex classes, making available to Octave
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
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1819 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	1820 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	1821 @var{classpath} is composed of two parts:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1822
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1823 @itemize
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1824 @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	1825
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1826 @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	1827 @end itemize
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1828
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1829 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	1830 @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	1831 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	1832 @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	1833 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	1834 @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	1835 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	1836 @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	1837 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	1838 @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	1839 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	1840 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	1841
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1842 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	1843 @file{classpath.txt}) are:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1844
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1845 @itemize
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1846 @item
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1847 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	1848 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	1849 @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	1850 'per Octave invocation' basis.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1851
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1852 @item
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1853 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	1854 @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	1855 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	1856 on a @nospell{'per user'} basis.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1857
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1858 @item
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1859 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	1860 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	1861 @file{javaclasspath.m} resides, usually something like
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1862 @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	1863 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	1864
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1865 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1866 which javaclasspath
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1867 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1868
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1869 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	1870 @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	1871 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	1872 @end itemize
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1873
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1874 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	1875 @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	1876 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	1877
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1878 Example:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1879
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1880 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1881 octave> base_path = "C:/Octave/java_files";
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1882
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1883 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	1884 octave> javaaddpath ([base_path, "/someclasses.jar"]);
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1885 octave> javaaddpath ([base_path, "/moreclasses.jar"]);
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1886
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1887 octave> # check the dynamic classpath
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1888 octave> p = javaclasspath;
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1889 octave> disp (p@{1@});
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1890 C:/Octave/java_files/someclasses.jar
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1891 octave> disp (p@{2@});
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1892 C:/Octave/java_files/moreclasses.jar
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1893
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1894 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	1895 octave> javarmpath ([base_path, "/someclasses.jar"]);
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/moreclasses.jar
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1899
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1900 octave> # provoke an error
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1901 octave> disp (p@{2@});
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1902 error: A(I): Index exceeds matrix dimension.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1903 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1904
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1905 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	1906 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	1907 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	1908 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	1909 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	1910 to the Java search path.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1911
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1912 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1913 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1914 # contents of .octaverc:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1915 addpath ("~/octave");
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1916 javaaddpath ("~/octave/myclasses.jar");
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1917 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1918 @end example
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 @c ------------------------------------------------------------------------
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1921 @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	1922 @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	1923
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1924 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	1925 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	1926 and with the given parameters.
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 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	1929 @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	1930 class @code{java.math.BigDecimal}.
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 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1933 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1934 javaObject ("java.math.BigDecimal", 1.001 );
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1935 javaObject ("java.math.BigDecimal", "1.001");
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1936 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1937 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1938
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1939 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	1940 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	1941 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	1942 @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	1943 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	1944 Octave variable.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1945
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1946 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1947 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1948 a = 1.001;
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1949 b = javaObject ("java.math.BigDecimal", a);
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1950 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1951 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1952
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1953 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	1954 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	1955 addition to the previous example:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1956
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1957 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1958 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1959 isjava (a)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1960 @result{} ans = 0
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1961 class (a)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1962 @result{} ans = double
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1963 isjava (b)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1964 @result{} ans = 1
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1965 class (b)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1966 @result{} ans = java.math.BigDecimal
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1967 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1968 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1969
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1970 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	1971
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1972 @example
23565 3a730821e4a2 doc: Peridoc grammarcheck of documentation. Rik <rik@octave.org> parents: 23220 diff changeset	1973 @group
23213 b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1974 a = javaObject ("java.lang.Double", 1.001);
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1975 b = javaObject ("java.math.BigDecimal", a);
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1976
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1977 isjava (a)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1978 @result{} ans = 1
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1979 class (a)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1980 @result{} ans = java.lang.Double
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1981 isjava (b)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1982 @result{} ans = 1
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1983 class (b)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1984 @result{} ans = java.math.BigDecimal
23565 3a730821e4a2 doc: Peridoc grammarcheck of documentation. Rik <rik@octave.org> parents: 23220 diff changeset	1985 @end group
23213 b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1986 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1987
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1988 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	1989 @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	1990 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	1991 @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	1992 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	1993
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1994
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1995 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	1996 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	1997 @ref{XREFjavaArray,javaArray,javaArray}.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1998
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	1999 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	2000
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2001 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2002 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2003 a.toString
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2004 @result{} ans = 1.001
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2005 b.toString
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2006 @result{} ans = 1.000999999999999889865...
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2007 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2008 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2009
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2010 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	2011 @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	2012 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	2013 with and without parentheses @code{()}.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2014
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2015 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	2016 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	2017 @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	2018
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2019 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2020 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2021 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	2022 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	2023 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2024 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2025
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2026 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	2027 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	2028 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	2029
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2030 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	2031 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	2032
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2033 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2034 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2035 java.math.BigDecimal.ONE; # does not work
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2036 java_get ("java.math.BigDecimal", "ONE"); # workaround
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2037 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2038 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2039
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2040 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	2041 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	2042 Octave.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2043
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2044 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	2045 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	2046
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2047 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2048 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2049 javaObject ("java.math.BigDecimal", []);
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2050 @result{} error: [java] java.lang.NullPointerException
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2051 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2052 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2053
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2054 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	2055 @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	2056 @code{double}.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2057
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2058 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	2059 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	2060
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2061 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2062 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2063 fieldnames (<Java object>)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2064 methods (<Java object>)
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2065 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2066 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2067
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2068 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	2069 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	2070 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	2071 the stack trace are displayed.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2072
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2073 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2074 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2075 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	2076 debug_java ()
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2077 @result{} ans = 1
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2078 javaObject ("java.math.BigDecimal", "1") ...
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2079 .divide (javaObject ("java.math.BigDecimal", "0"))
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2080 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2081 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2082
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2083
25816 98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2084 @node Set up the JVM
98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2085 @subsection Set up the JVM
23213 b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2086 @cindex memory, limitations on JVM
26048 d02e4b1df697 doc: Spellcheck documentation. Rik <rik@octave.org> parents: 26047 diff changeset	2087 @cindex select JVM version
25816 98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2088
98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2089 In order to execute Java code Octave creates a Java Virtual Machine (JVM). By
98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2090 default the version of the JVM is used that was detected during configuration
98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2091 on Unix-like systems or that is pointed to from the registry keys at
98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2092 @file{HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\JRE} or
98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2093 @file{HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Runtime Environment} on
26171 00b3e20eb3bc doc: Change "overwritten" to "overridden" in Java docs (bug #40111). Rik <rik@octave.org> parents: 26048 diff changeset	2094 Windows. The default path to the JVM can be overridden by setting the
25816 98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2095 environment variable @w{@env{JAVA_HOME}} to the path where the JVM is
26047 1357b79f87bc doc: grammar check txi files in doc/interpreter/ directory. Rik <rik@octave.org> parents: 25816 diff changeset	2096 installed. On Windows that might be, for example,
1357b79f87bc doc: grammar check txi files in doc/interpreter/ directory. Rik <rik@octave.org> parents: 25816 diff changeset	2097 @file{C:\Program Files\Java\jre-10.0.2}. Make sure that you select a directory
26048 d02e4b1df697 doc: Spellcheck documentation. Rik <rik@octave.org> parents: 26047 diff changeset	2098 that contains the JVM with a @nospell{bit-ness} that matches Octave's.
25816 98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2099
98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2100 The JVM is only loaded once per Octave session. Thus, to change the used
98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2101 version of the JVM, you might have to re-start Octave. To check which version
98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2102 of the JVM is currently being used, run @code{version -java}.
98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2103
98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2104 The JVM allocates a fixed amount of initial memory and may expand this pool up
98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2105 to a fixed maximum memory limit. The default values depend on the Java version
98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2106 (@pxref{XREFjavamem,,javamem}). The memory pool is shared by all Java objects
98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2107 running in the JVM@. This strict memory limit is intended mainly to avoid
98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2108 runaway applications inside web browsers or in enterprise servers which can
98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2109 consume all memory and crash the system. When the maximum memory limit is hit,
98242f7e8a0b Document how the JVM can be selected at load time (bug #49111). Markus Mützel <markus.muetzel@gmx.de> parents: 25143 diff changeset	2110 Java code will throw exceptions so that applications will fail or behave
23213 b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2111 unexpectedly.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2112
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2113 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	2114 @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	2115 @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	2116 initialization.
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 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	2119 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	2120 @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	2121 @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	2122 You can find this directory by executing
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2123
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2124 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2125 which javaclasspath
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2126 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2127
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2128 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	2129 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	2130 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	2131
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2132 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2133 -Xmx256m
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2134 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2135
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2136 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	2137 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	2138 about 1 Gigabyte.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2139
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2140 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	2141 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	2142 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	2143 Megabytes of initial memory:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2144
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2145 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2146 -Xms64m
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2147 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2148
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2149 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	2150 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	2151 and consult the Java documentation.
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 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	2154 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	2155 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	2156 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	2157 the string @code{12.34}.
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2158
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2159 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2160 -DMyProperty=12.34
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2161 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2162
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2163 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	2164 or in Octave:
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2165
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2166 @example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2167 @group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2168 octave> javaMethod ("getProperty", "java.lang.System", "MyProperty");
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2169 ans = 12.34
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2170 @end group
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2171 @end example
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2172
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2173 @seealso{javamem}
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2174
b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2175
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2176 @node Java Interface Functions
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2177 @subsection Java Interface Functions
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2178
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2179 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	2180 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	2181 which return results to Octave.
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2182
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2183 @cindex object, creating a Java object
23213 b8a186a9760b doc: Overhaul Java interface description (bug #50299) Ernst Reissner <rei3ner@arcor.de> parents: 23083 diff changeset	2184 @cindex instance, creating a Java instance
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2185 @DOCSTRING(javaObject)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2186
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2187 @cindex array, creating a Java array
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2188 @DOCSTRING(javaArray)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2189
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2190 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	2191 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	2192 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	2193
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2194 @DOCSTRING(isjava)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2195
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2196 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	2197 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	2198
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2199 @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	2200 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	2201 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	2202
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2203 @example
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2204 @group
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2205 dobj = javaObject ("java.lang.Double", pi);
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2206 fieldnames (dobj)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2207 @result{}
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2208 @{
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2209 [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	2210 [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	2211 [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	2212 [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	2213 [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	2214 [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	2215 [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	2216 [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	2217 [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	2218 [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	2219 @}
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2220 @end group
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2221 @end example
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2222
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2223 @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	2224 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	2225 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	2226 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	2227 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	2228 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	2229
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2230 @example
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2231 @group
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2232 dobj = javaObject ("java.lang.Double", pi);
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2233 dobj.MAX_VALUE
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2234 @result{} 1.7977e+308
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2235 java_get ("java.lang.Float", "MAX_VALUE")
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2236 @result{} 3.4028e+38
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2237 @end group
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2238 @end example
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 @DOCSTRING(java_get)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2241
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2242 @cindex field, setting value of Java object field
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2243 @DOCSTRING(java_set)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2244
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2245 @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	2246 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	2247 example, using the previously created @var{dobj}:
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2248
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2249 @example
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2250 @group
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2251 methods (dobj)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2252 @result{}
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2253 Methods for class java.lang.Double:
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2254 boolean equals(java.lang.Object)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2255 java.lang.String toString(double)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2256 java.lang.String toString()
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2257 @dots{}
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2258 @end group
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2259 @end example
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2260
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2261 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	2262 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	2263 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	2264 below.
21630 b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2265
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2266 @example
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2267 @group
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2268 dobj = javaObject ("java.lang.Double", pi);
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2269 dobj.equals (3)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2270 @result{} 0
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2271 javaMethod ("equals", dobj, pi)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2272 @result{} 1
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2273 @end group
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2274 @end example
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2275
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2276 @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	2277 @DOCSTRING(javaMethod)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2278
22970 cc025b4bd2fb doc: Review Appendix A, External Code Interface, of manual. Rik <rik@octave.org> parents: 22924 diff changeset	2279 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	2280 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	2281 @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	2282
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2283 @cindex classpath, displaying
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2284 @cindex classpath, dynamic
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2285 @cindex dynamic classpath
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2286 @cindex classpath, static
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2287 @cindex static classpath
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2288 @DOCSTRING(javaclasspath)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2289
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2290 @findex javaaddpath
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2291 @cindex classpath, adding new path
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2292 @cindex path, adding to classpath
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2293 @cindex classpath, dynamic
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2294 @cindex dynamic classpath, adding new path
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2295 @DOCSTRING(javaaddpath)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2296
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2297 @cindex classpath, removing path
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2298 @cindex path, removing from classpath
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2299 @DOCSTRING(javarmpath)
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 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	2302 between Octave and the Java Virtual Machine.
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2303
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2304 @DOCSTRING(javachk)
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(usejava)
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 @cindex memory, displaying Java memory status
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2309 @DOCSTRING(javamem)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2310
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2311 @DOCSTRING(java_matrix_autoconversion)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2312
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2313 @DOCSTRING(java_unsigned_autoconversion)
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2314
b5d9b95d1e1a Removing Java dialog boxes. Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 21530 diff changeset	2315 @DOCSTRING(debug_java)

Mercurial > octave

annotate doc/interpreter/external.txi @ 31548:c8ad083a5802 stable