octave: doc/interpreter/external.txi annotate

annotate doc/interpreter/external.txi @ 22299:9fc91bb2aec3

doc: grammarcheck documentation for 4.2 release. * container.txi, contrib.txi, diagperm.txi, errors.txi, external.txi, func.txi, image.txi, nonlin.txi, numbers.txi, plot.txi, quad.txi, sparse.txi, strings.txi, tips.txi, var.txi, vectorize.txi, __dispatch__.cc, cellfun.cc, file-io.cc, gsvd.cc, load-path.cc, regexp.cc, __init_gnuplot__.cc, __osmesa_print__.cc, qr.cc, xzip.cc, ov-classdef.cc, octave_config_info.m, grabcode.m, publish.m, dialog.m, condest.m, normest1.m, mkdir.m, ode23.m, ode45.m, odeplot.m, AbsRel_Norm.m, integrate_adaptive.m, integrate_const.m, integrate_n_steps.m, axis.m, isocaps.m, isocolors.m, isosurface.m, light.m, __calc_isovalue_from_data__.m, __marching_cube__.m, cov.m, median.m: doc: grammarcheck documentation for 4.2 release.

author	Rik <rik@octave.org>
date	Mon, 15 Aug 2016 10:05:50 -0700
parents	b5d9b95d1e1a
children	609403f90bb7

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

Mercurial > octave

annotate doc/interpreter/external.txi @ 22299:9fc91bb2aec3