octave-nkf: doc/interpreter/external.txi annotate

annotate doc/interpreter/external.txi @ 18602:f51c1498b9f3 stable

doc: Replace "builtin" with "built-in" for consistency and correctness. * external.txi, func.txi, testfun.txi, doc_cache_create.m: Replace "builtin" with "built-in" for consistency and correctness.

author	Rik <rik@octave.org>
date	Sat, 01 Mar 2014 22:04:59 -0800
parents	4b32677b6229
children	322eb69e30ad

rev	line source
17744 d63878346099 maint: Update copyright notices for release. John W. Eaton <jwe@octave.org> parents: 17289 diff changeset	1 @c Copyright (C) 2007-2013 John W. Eaton and David Bateman
7018 fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	2 @c Copyright (C) 2007 Paul Thomas and Christoph Spiel
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	3 @c
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	4 @c This file is part of Octave.
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	5 @c
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	6 @c Octave is free software; you can redistribute it and/or modify it
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	7 @c under the terms of the GNU General Public License as published by the
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	8 @c Free Software Foundation; either version 3 of the License, or (at
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	9 @c your option) any later version.
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	10 @c
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	11 @c Octave is distributed in the hope that it will be useful, but WITHOUT
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	12 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	13 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	14 @c for more details.
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	15 @c
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	16 @c You should have received a copy of the GNU General Public License
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	17 @c along with Octave; see the file COPYING. If not, see
fd42779a8428 [project @ 2007-10-13 00:52:12 by jwe] jwe parents: 7007 diff changeset	18 @c <http://www.gnu.org/licenses/>.
6578 fbc16fe0e86a [project @ 2007-04-25 16:04:59 by jwe] jwe parents: 6577 diff changeset	19
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	20 @node External Code Interface
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	21 @appendix External Code Interface
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	22 @cindex dynamic-linking
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	23 @cindex Dynamically Linked Functions
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	24 @cindex Octave API
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	25
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	26 “The sum of human wisdom is not contained in any one language"
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	27 ---Ezra Pound
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	28
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	29 Octave is a fantastic language for solving many problems in science and
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	30 engineering. However, it is not the only computer language and there
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	31 are times when you may want to use code written in other languages.
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	32 Good reasons for doing so include: 1) not re-inventing the wheel; existing
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	33 function libraries which have been thoroughly tested and debugged or
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	34 large scale simulation codebases are a good example, 2) accessing unique
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	35 capabilities of a different language; for example the well-known regular
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	36 expression functions of Perl (but don't do that because @code{regexp}
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	37 already exists in Octave).
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	38
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	39 Performance should generally @strong{not} be a reason for using compiled
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	40 extensions. Although compiled extensions can run faster, particularly
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	41 if they replace a loop in Octave code, this is almost never the best path
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	42 to take. First, there are many techniques to speed up Octave performance while
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	43 remaining within the language. Second, Octave is a high-level language that
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	44 makes it easy to perform common mathematical tasks. Giving that up means
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	45 shifting the focus from solving the real problem to solving a computer
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	46 programming problem. It means returning to low-level constructs such as
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	47 pointers, memory management, mathematical overflow/underflow, etc. Because
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	48 of the low level nature, and the fact that the compiled code is executed outside
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	49 of Octave, there is the very real possibility of crashing the interpreter and
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	50 losing work.
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	51
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	52 Before going further, you should first determine if you really need to bother
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	53 writing code outside of Octave.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	54
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	55 @itemize @bullet
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	56 @item
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	57 Can I get the same functionality using the Octave scripting language alone?
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	58
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	59 Even when a function already exists outside the language, it may be
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	60 better to simply reproduce the behavior in an m-file rather than attempt to
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	61 interface to the outside code.
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	62
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	63 @item
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	64 Is the code thoroughly optimized for Octave?
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	65
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	66 If performance is an issue you should always start with the in-language
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	67 techniques for getting better performance. Chief among these is vectorization
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	68 (@pxref{Vectorization and Faster Code Execution}) which not only makes the
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	69 code concise and more understandable but improves performance (10X-100X).
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	70 If loops must be used, make sure that the allocation of space for variables
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	71 takes place outside the loops using an assignment to a matrix of the right
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	72 size, or zeros.
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	73
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	74 @item
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	75 Does the code make as much use as possible of existing built-in library
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	76 routines?
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	77
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	78 These routines are highly optimized and many do not carry the overhead
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	79 of being interpreted.
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	80
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	81 @item
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	82 Does writing a dynamically linked function represent a useful investment
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	83 of your time, relative to staying in Octave?
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	84
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	85 It will take time to learn Octave's interface for external code and
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	86 there will inevitably be issues with tools such as compilers.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	87 @end itemize
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	88
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	89 With that said, Octave offers a versatile interface for including chunks
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	90 of compiled code as dynamically linked extensions. These dynamically linked
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	91 functions can be called from the interpreter in the same manner as any
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	92 ordinary function. The interface is bi-directional and external code can
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	93 call Octave functions (like @code{plot}) which otherwise might be very
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	94 difficult to develop.
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	95
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	96 The interface is centered around supporting the languages C++, C, and Fortran.
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	97 Octave itself is written in C++ and can call external C++/C code through its
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	98 native oct-file interface. The C language is also supported through the
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	99 mex-file interface for compatibility with @sc{matlab}. Fortran code is easiest
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	100 to reach through the oct-file interface.
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	101
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	102 Because many other languages provide C or C++ APIs it is relatively simple
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	103 to build bridges between Octave and other languages. This is also a way to
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	104 bridge to hardware resources which often have device drivers written in C.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	105
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	106 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	107 * Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	108 * Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	109 * Standalone Programs::
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	110 @end menu
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	111
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	112 @node Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	113 @section Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	114 @cindex oct-files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	115 @cindex mkoctfile
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	116 @cindex oct
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	117
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	118 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	119 * Getting Started with Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	120 * Matrices and Arrays in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	121 * Character Strings in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	122 * Cell Arrays in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	123 * Structures in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	124 * Sparse Matrices in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	125 * Accessing Global Variables in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	126 * Calling Octave Functions from Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	127 * Calling External Code from Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	128 * Allocating Local Memory in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	129 * Input Parameter Checking in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	130 * Exception and Error Handling in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	131 * Documentation and Test of Oct-Files::
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	132 @c * Application Programming Interface for Oct-Files::
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	133 @end menu
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	134
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	135 @node Getting Started with Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	136 @subsection Getting Started with Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	137
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	138 Oct-files are pieces of C++ code that have been compiled with the Octave
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	139 API into a dynamically loadable object. They take their name from the file
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	140 which contains the object which has the extension @file{.oct}.
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	141
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	142 Finding a C++ compiler, using the correct switches, adding the right include
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	143 paths for header files, etc. is a difficult task. Octave automates this by
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	144 providing the @code{mkoctfile} command with which to build oct-files. The
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	145 command is available from within Octave or at the shell command line.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	146
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	147 @DOCSTRING(mkoctfile)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	148
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	149 Consider the following short example which introduces the basics of
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	150 writing a C++ function that can be linked to Octave.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	151
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	152 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	153 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	154 @EXAMPLEFILE(helloworld.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	155 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	156 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	157
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	158 The first critical line is @code{#include <octave/oct.h>} which
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	159 makes available most of the definitions necessary for a C++ oct-file.
12489 ac3bdc27734e Clarify in manual that the mkoctfile examples are in C++ Jordi Gutiérrez Hermoso <jordigh@gmail.com> parents: 11573 diff changeset	160 Note that @file{octave/oct.h} is a C++ header and cannot be directly
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	161 @code{#include}'ed in a C source file, nor any other language.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	162
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	163 Included by @file{oct.h} is a definition for the macro
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	164 @w{@code{DEFUN_DLD}} which creates a dynamically loaded function. This
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	165 macro takes four arguments:
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	166
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	167 @enumerate 1
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	168 @item The function name as it will be seen in Octave,
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	169
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	170 @item The list of arguments to the function of type @code{octave_value_list},
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	171
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	172 @item The number of output arguments, which can and often is omitted if
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	173 not used, and
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	174
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	175 @item The string to use for the help text of the function.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	176 @end enumerate
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	177
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9080 diff changeset	178 The return type of functions defined with @w{@code{DEFUN_DLD}} is always
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	179 @code{octave_value_list}.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	180
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	181 There are a couple of important considerations in the choice of function
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	182 name. First, it must be a valid Octave function name and so must be a
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	183 sequence of letters, digits, and underscores not starting with a
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	184 digit. Second, as Octave uses the function name to define the filename
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	185 it attempts to find the function in, the function name in the
322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	186 @w{@code{DEFUN_DLD}} macro must match the filename of the oct-file. Therefore,
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	187 the above function should be in a file @file{helloworld.cc}, and would be
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	188 compiled to an oct-file using the command
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	189
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	190 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	191 mkoctfile helloworld.cc
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	192 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	193
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	194 This will create a file called @file{helloworld.oct} that is the compiled
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	195 version of the function. It should be noted that it is perfectly
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9080 diff changeset	196 acceptable to have more than one @w{@code{DEFUN_DLD}} function in a source
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	197 file. However, there must either be a symbolic link to the oct-file for
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9080 diff changeset	198 each of the functions defined in the source code with the @w{@code{DEFUN_DLD}}
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	199 macro or the @code{autoload} (@ref{Function Files}) function should be used.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	200
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	201 The rest of the function shows how to find the number of input arguments,
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	202 how to print through the Octave pager, and return from the function. After
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	203 compiling this function as above, an example of its use is
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	204
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	205 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	206 @group
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	207 helloworld (1, 2, 3)
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	208 @print{} Hello World has 3 input arguments and 0 output arguments.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	209 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	210 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	211
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	212 Subsequent sections show how to use specific classes from Octave's core
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	213 internals. Base classes like dMatrix (a matrix of double values) are
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	214 found in the directory @file{liboctave/array}. The definitive reference for
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	215 how to use a particular class is the header file itself. However, it is
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	216 often enough just to study the examples in the manual in order to be able
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	217 to use the class.
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	218
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	219 @node Matrices and Arrays in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	220 @subsection Matrices and Arrays in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	221
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	222 Octave supports a number of different array and matrix classes, the
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	223 majority of which are based on the Array class. The exception is the
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	224 sparse matrix types discussed separately below. There are three basic
24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	225 matrix types
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	226
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	227 @table @code
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	228 @item Matrix
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	229 A double precision matrix class defined in @file{dMatrix.h},
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	230
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	231 @item ComplexMatrix
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	232 A complex matrix class defined in @file{CMatrix.h}, and
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	233
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	234 @item BoolMatrix
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	235 A boolean matrix class defined in @file{boolMatrix.h}.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	236 @end table
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	237
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	238 These are the basic two-dimensional matrix types of Octave. In
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	239 addition there are a number of multi-dimensional array types including
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	240
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	241 @table @code
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	242 @item NDArray
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	243 A double precision array class defined in @file{dNDArray.h}
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	244
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	245 @item ComplexNDarray
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	246 A complex array class defined in @file{CNDArray.h}
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	247
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	248 @item boolNDArray
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	249 A boolean array class defined in @file{boolNDArray.h}
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	250
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	251 @item int8NDArray
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	252 @itemx int16NDArray
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	253 @itemx int32NDArray
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	254 @itemx int64NDArray
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	255 8, 16, 32, and 64-bit signed array classes defined in
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	256 @file{int8NDArray.h}, @file{int16NDArray.h}, etc.
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	257
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	258 @item uint8NDArray
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	259 @itemx uint16NDArray
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	260 @itemx uint32NDArray
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	261 @itemx uint64NDArray
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	262 8, 16, 32, and 64-bit unsigned array classes defined in
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	263 @file{uint8NDArray.h}, @file{uint16NDArray.h}, etc.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	264 @end table
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	265
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	266 There are several basic ways of constructing matrices or
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	267 multi-dimensional arrays. Using the class @code{Matrix} as an example
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	268 one can
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	269
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	270 @itemize @bullet
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	271 @item
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	272 Create an empty matrix or array with the empty constructor. For example:
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	273
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	274 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	275 Matrix a;
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	276 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	277
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	278 This can be used for all matrix and array types.
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	279
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	280 @item
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	281 Define the dimensions of the matrix or array with a dim_vector which has
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	282 the same characteristics as the vector returned from @code{size}. For example:
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	283
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	284 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	285 @group
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	286 dim_vector dv (2);
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	287 dv(0) = 2; dv(1) = 3; // 2 rows, 3 columns
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	288 Matrix a (dv);
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	289 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	290 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	291
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	292 This can be used on all matrix and array types.
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	293
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	294 @item
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	295 Define the number of rows and columns in the matrix. For example:
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	296
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	297 @example
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	298 Matrix a (2, 2)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	299 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	300
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	301 However, this constructor can only be used with matrix types.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	302 @end itemize
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	303
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	304 These types all share a number of basic methods and operators. Many bear
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	305 a resemblance to functions that exist in the interpreter. A selection of
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	306 useful methods include
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	307
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	308 @deftypefn {Method} {T&} operator () (octave_idx_type)
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	309 @deftypefnx {Method} {T&} elem (octave_idx_type)
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	310 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	311 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	312 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	313 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	314 @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	315 value to obtain or set.
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	316 @end deftypefn
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	317
7001 8b0cfeb06365 [project @ 2007-10-10 18:02:59 by jwe] jwe parents: 6939 diff changeset	318 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	319 circumstances the user might prefer to access the data of the array or
10791 3140cb7a05a1 Add spellchecker scripts for Octave and run spellcheck of documentation Rik <octave@nomad.inbox5.com> parents: 9906 diff changeset	320 matrix directly through the @nospell{fortran_vec} method discussed below.
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	321
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	322 @deftypefn {Method} {} octave_idx_type numel (void) const
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	323 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	324 @end deftypefn
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	325
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	326 @deftypefn {Method} {size_t} byte_size (void) const
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	327 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	328 @end deftypefn
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	329
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	330 @deftypefn {Method} {dim_vector} dims (void) const
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	331 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	332 @end deftypefn
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	333
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	334 @deftypefn {Method} {int} ndims (void) const
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	335 The number of dimensions of the matrix or array. Matrices are 2-D,
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	336 but arrays can be N-dimensional.
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	337 @end deftypefn
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	338
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	339 @deftypefn {Method} {void} resize (const dim_vector&)
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	340 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	341 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	342 the number of rows and columns in the matrix.
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	343 @end deftypefn
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	344
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	345 @deftypefn {Method} {T*} fortran_vec (void)
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	346 This method returns a pointer to the underlying data of the matrix or
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	347 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	348 an external library.
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	349 @end deftypefn
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	350
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	351 Operators such an @code{+}, @code{-}, or @code{*} can be used on the
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	352 majority of the matrix and array types. In addition there are a number of
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	353 methods that are of interest only for matrices such as @code{transpose},
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	354 @code{hermitian}, @code{solve}, etc.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	355
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	356 The typical way to extract a matrix or array from the input arguments of
9209 923c7cb7f13f Simplify TeXinfo files by eliminating redundant @iftex followed by @tex construction. Rik <rdrider0-list@yahoo.com> parents: 9080 diff changeset	357 @w{@code{DEFUN_DLD}} function is as follows
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	358
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	359 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	360 @EXAMPLEFILE(addtwomatrices.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	361 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	362
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	363 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	364 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	365 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	366 of type @code{NDArray} and adds these together. Note that the array_value
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	367 method is called without using the @code{is_matrix_type} type, and instead the
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	368 error_state is checked before returning @code{A + B}. The reason to
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	369 prefer this is that the arguments might be a type that is not an
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	370 @code{NDArray}, but it would make sense to convert it to one. The
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	371 @code{array_value} method allows this conversion to be performed
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	372 transparently if possible, and sets @code{error_state} if it is not.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	373
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	374 @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	375 @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	376 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	377
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	378 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	379 @group
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	380 addtwomatrices (ones (2, 2), eye (2, 2))
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	381 @result{} 2 1
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	382 1 2
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	383 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	384 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	385
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	386 A list of the basic @code{Matrix} and @code{Array} types, the methods to
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	387 extract these from an @code{octave_value}, and the associated header file is
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	388 listed below.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	389
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	390 @multitable @columnfractions .3 .4 .3
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	391 @headitem Type @tab Function @tab Source Code
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	392 @item @code{RowVector} @tab @code{row_vector_value} @tab @file{dRowVector.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	393 @item @code{ComplexRowVector} @tab @code{complex_row_vector_value} @tab @file{CRowVector.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	394 @item @code{ColumnVector} @tab @code{column_vector_value} @tab @file{dColVector.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	395 @item @code{ComplexColumnVector} @tab @code{complex_column_vector_value} @tab @file{CColVector.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	396 @item @code{Matrix} @tab @code{matrix_value} @tab @file{dMatrix.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	397 @item @code{ComplexMatrix} @tab @code{complex_matrix_value} @tab @file{CMatrix.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	398 @item @code{boolMatrix} @tab @code{bool_matrix_value} @tab @file{boolMatrix.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	399 @item @code{charMatrix} @tab @code{char_matrix_value} @tab @file{chMatrix.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	400 @item @code{NDArray} @tab @code{array_value} @tab @file{dNDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	401 @item @code{ComplexNDArray} @tab @code{complex_array_value} @tab @file{CNDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	402 @item @code{boolNDArray} @tab @code{bool_array_value} @tab @file{boolNDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	403 @item @code{charNDArray} @tab @code{char_array_value} @tab @file{charNDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	404 @item @code{int8NDArray} @tab @code{int8_array_value} @tab @file{int8NDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	405 @item @code{int16NDArray} @tab @code{int16_array_value} @tab @file{int16NDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	406 @item @code{int32NDArray} @tab @code{int32_array_value} @tab @file{int32NDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	407 @item @code{int64NDArray} @tab @code{int64_array_value} @tab @file{int64NDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	408 @item @code{uint8NDArray} @tab @code{uint8_array_value} @tab @file{uint8NDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	409 @item @code{uint16NDArray} @tab @code{uint16_array_value} @tab @file{uint16NDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	410 @item @code{uint32NDArray} @tab @code{uint32_array_value} @tab @file{uint32NDArray.h}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	411 @item @code{uint64NDArray} @tab @code{uint64_array_value} @tab @file{uint64NDArray.h}
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	412 @end multitable
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	413
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	414 @node Character Strings in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	415 @subsection Character Strings in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	416
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	417 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	418 Consider the example:
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	419
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	420 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	421 @EXAMPLEFILE(stringdemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	422 @end example
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	423
9080 ec41eabf4499 Cleanup documentation files dynamic.texi, testfun.texi, tips.texi Rik <rdrider0-list@yahoo.com> parents: 9038 diff changeset	424 An example of the use of this function is
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	425
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	426 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	427 @group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	428 s0 = ["First String"; "Second String"];
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	429 [s1,s2] = stringdemo (s0)
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	430 @result{} s1 = Second String
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	431 First String
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	432
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	433 @result{} s2 = First String
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	434 Second String
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	435
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	436 typeinfo (s2)
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	437 @result{} sq_string
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	438 typeinfo (s1)
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	439 @result{} string
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	440 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	441 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	442
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	443 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	444 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	445 @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	446 one of the predicate tests shown below.
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	447
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	448 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	449 @group
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	450 if (args(0).is_sq_string ())
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	451 octave_stdout << "First argument is a single quoted string\n";
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	452 else if (args(0).is_dq_string ())
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	453 octave_stdout << "First argument is a double quoted string\n";
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	454 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	455 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	456
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	457 Note, however, that both types of strings are represented by the
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	458 @code{charNDArray} type, and so when assigning to an
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	459 @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	460
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	461 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	462 @group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	463 octave_value_list retval;
18426 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	464 charNDArray ch;
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	465 @dots{}
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	466 // Create single quoted string
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	467 retval(1) = octave_value (ch); // default constructor is sq_string
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	468 OR
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	469 retval(1) = octave_value (ch, '\''); // explicitly create sq_string
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	470
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	471 // Create a double quoted string
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	472 retval(0) = octave_value (ch, '"');
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	473 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	474 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	475
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	476 @node Cell Arrays in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	477 @subsection Cell Arrays in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	478
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	479 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	480 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	481 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	482 example is
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	483
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	484 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	485 @EXAMPLEFILE(celldemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	486 @end example
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	487
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	488 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	489 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	490 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	491 returns them as individual return arguments. For example:
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	492
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	493 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	494 @group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	495 [b1, b2, b3] = celldemo (@{1, [1, 2], "test"@})
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	496 @result{}
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	497 b1 = 1
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	498 b2 =
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	499
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	500 1 2
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	501
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	502 b3 = test
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	503 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	504 @end example
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 @node Structures in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	507 @subsection Structures in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	508
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	509 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	510 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	511 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	512 @code{Cell} variable.
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	513
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	514 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	515
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	516 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	517 @EXAMPLEFILE(structdemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	518 @end example
6572 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 An example of its use is
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	521
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	522 @example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	523 @group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	524 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	525 structdemo (x, "b")
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	526 @result{} selected = test
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	527 @end group
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	528 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	529
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	530 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	531 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	532 @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	533 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	534 @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	535 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	536 this single-struct example we write
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	537
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	538 @example
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	539 octave_value tmp = arg0.contents (arg1)(0);
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	540 @end example
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	541
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	542 @noindent
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	543 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	544 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	545 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	546
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	547 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	548 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	549 than relying on just @code{contents}.
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	550
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	551 @node Sparse Matrices in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	552 @subsection Sparse Matrices in Oct-Files
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	553
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	554 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	555
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	556 @table @code
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	557 @item SparseMatrix
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	558 A double precision sparse matrix class
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	559
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	560 @item SparseComplexMatrix
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	561 A complex sparse matrix class
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	562
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	563 @item SparseBoolMatrix
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	564 A boolean sparse matrix class
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	565 @end table
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	566
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	567 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	568 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	569 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	570 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	571 the sparse classes.
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 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	574 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	575 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	576 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	577 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	578 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	579 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	580 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	581
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	582 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	583 * Array and Sparse Class Differences::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	584 * Creating Sparse Matrices in Oct-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	585 * Using Sparse Matrices in Oct-Files::
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	586 @end menu
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	587
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	588 @node Array and Sparse Class Differences
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	589 @subsubsection Array and Sparse Class Differences
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	590
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	591 The number of elements in a sparse matrix is considered to be the number
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	592 of non-zero elements rather than the product of the dimensions. Therefore
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	593
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	594 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	595 @group
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	596 SparseMatrix sm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	597 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	598 int nel = sm.nelem ();
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	599 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	600 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	601
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	602 @noindent
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	603 returns the number of non-zero elements. If the user really requires the
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	604 number of elements in the matrix, including the non-zero elements, they
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	605 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	606 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	607 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	608 An example is @code{speye (1e6)} which will create a matrix with a million
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	609 rows and columns, but only a million non-zero elements. Therefore the
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	610 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	611 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	612 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	613 it won't overflow.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	614
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	615 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	616 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	617 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	618 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	619 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	620 code like
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	621
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	622 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	623 @group
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	624 SparseMatrix sm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	625 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	626 for (int j = 0; j < nc; j++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	627 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	628 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	629 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	630 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	631
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	632 @noindent
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	633 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	634 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	635 zero element in the matrix.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	636
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	637 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	638 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	639 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	640 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	641 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	642
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	643 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	644 @group
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	645 SparseMatrix sm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	646 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	647 const SparseMatrix tmp (sm);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	648 for (int j = 0; j < nc; j++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	649 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	650 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	651 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	652 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	653
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	654 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	655 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	656 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	657 @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	658 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	659 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	660 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	661 matrix compressed column format.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	662
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	663 @node Creating Sparse Matrices in Oct-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	664 @subsubsection Creating Sparse Matrices in Oct-Files
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	665
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	666 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	667 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	668 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	669 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	670 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	671 advantages and disadvantages.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	672
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	673 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	674 technique
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	675
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	676 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	677 @group
18426 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	678 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	679 nz = 4, nr = 3, nc = 4;
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	680
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	681 ColumnVector ridx (nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	682 ColumnVector cidx (nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	683 ColumnVector data (nz);
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	684
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	685 ridx(0) = 0; cidx(0) = 0; data(0) = 1;
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	686 ridx(1) = 0; cidx(1) = 1; data(1) = 2;
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	687 ridx(2) = 1; cidx(2) = 3; data(2) = 3;
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	688 ridx(3) = 2; cidx(3) = 3; data(3) = 4;
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	689 SparseMatrix sm (data, ridx, cidx, nr, nc);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	690 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	691 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	692
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	693 @noindent
8817 03b7f618ab3d include docstrings for new functions in the manual John W. Eaton <jwe@octave.org> parents: 8486 diff changeset	694 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	695 @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	696 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	697 but is used internally.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	698
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	699 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	700 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	701 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	702 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	703
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	704 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	705 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	706 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	707 technique for creating a sparse matrix.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	708
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	709 The alternative is to first create a sparse matrix with the desired
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	710 number of non-zero elements and then later fill those elements in.
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	711 Sample code:
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	712
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	713 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	714 @group
18426 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	715 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	716 nz = 4, nr = 3, nc = 4;
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	717 SparseMatrix sm (nr, nc, nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	718 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	719 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	720 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	721
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	722 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	723 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	724 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	725 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	726 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	727 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	728
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	729 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	730 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	731 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	732
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	733 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	734 @group
18426 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	735 int nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	736 nr = 3, nc = 4;
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	737 SparseMatrix sm (nr, nc, 0);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	738 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	739 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	740 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	741
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	742 @noindent
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	743 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	744 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	745 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	746 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	747 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	748 @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	749 occupies more memory than strictly needed.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	750
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	751 It is not always possible to know the number of non-zero elements prior
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	752 to filling a matrix. For this reason the additional unused storage of
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	753 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	754 @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	755 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	756 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	757 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	758 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	759 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	760 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	761 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	762
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	763 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	764 @group
18426 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	765 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	766 nz = 6, nr = 3, nc = 4;
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	767
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	768 SparseMatrix sm1 (nr, nc, nz);
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	769 sm1(0,0) = 1; sm1(0,1) = 2; sm1(1,3) = 3; sm1(2,3) = 4;
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	770 sm1.maybe_compress (); // No zero elements were added
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	771
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	772 SparseMatrix sm2 (nr, nc, nz);
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	773 sm2(0,0) = 1; sm2(0,1) = 2; sm(0,2) = 0; sm(1,2) = 0;
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	774 sm1(1,3) = 3; sm1(2,3) = 4;
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	775 sm2.maybe_compress (true); // Zero elements were added
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	776 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	777 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	778
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	779 The use of the @code{maybe_compress} function should be avoided if
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	780 possible as it will slow the creation of the matrix.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	781
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	782 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	783 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	784 be
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	785
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	786 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	787 octave_value arg;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	788 @dots{}
18426 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	789 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	790 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	791 SparseMatrix sm (nr, nc, nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	792 Matrix m = arg.matrix_value ();
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	793
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	794 int ii = 0;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	795 sm.cidx (0) = 0;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	796 for (int j = 1; j < nc; j++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	797 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	798 for (int i = 0; i < nr; i++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	799 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	800 double tmp = foo (m(i,j));
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	801 if (tmp != 0.)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	802 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	803 sm.data(ii) = tmp;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	804 sm.ridx(ii) = i;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	805 ii++;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	806 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	807 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	808 sm.cidx(j+1) = ii;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	809 @}
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	810 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	811 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	812
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	813 @noindent
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	814 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	815
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	816 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	817 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	818 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	819 The above example would then be modified as
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	820
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	821 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	822 octave_value arg;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	823 @dots{}
18426 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	824 int nz, nr, nc;
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	825 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	826 SparseMatrix sm (nr, nc, nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	827 Matrix m = arg.matrix_value ();
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	828
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	829 int ii = 0;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	830 sm.cidx (0) = 0;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	831 for (int j = 1; j < nc; j++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	832 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	833 for (int i = 0; i < nr; i++)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	834 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	835 double tmp = foo (m(i,j));
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	836 if (tmp != 0.)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	837 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	838 if (ii == nz)
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	839 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	840 nz += 2; // Add 2 more elements
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	841 sm.change_capacity (nz);
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	842 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	843 sm.data(ii) = tmp;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	844 sm.ridx(ii) = i;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	845 ii++;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	846 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	847 @}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	848 sm.cidx(j+1) = ii;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	849 @}
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	850 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	851 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	852
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	853 Note that both increasing and decreasing the number of non-zero elements in
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	854 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	855 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	856 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	857 should be avoided.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	858
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	859 @node Using Sparse Matrices in Oct-Files
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	860 @subsubsection Using Sparse Matrices in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	861
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	862 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	863 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	864 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	865 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	866 following example.
6569 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 @example
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	869 @group
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	870 octave_value_list retval;
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	871
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	872 SparseMatrix sm = args(0).sparse_matrix_value ();
7081 503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	873 SparseComplexMatrix scm =
503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	874 args(1).sparse_complex_matrix_value ();
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	875 SparseBoolMatrix sbm = args(2).sparse_bool_matrix_value ();
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	876 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	877 retval(2) = sbm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	878 retval(1) = scm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	879 retval(0) = sm;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	880 @end group
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	881 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	882
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	883 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	884 @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	885
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	886 @node Accessing Global Variables in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	887 @subsection Accessing Global Variables in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	888
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	889 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	890 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	891 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	892 @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	893 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	894 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	895 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	896
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	897 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	898 @EXAMPLEFILE(globaldemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	899 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	900
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	901 An example of its use is
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	902
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	903 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	904 @group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	905 global a b
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	906 b = 10;
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	907 globaldemo ("b")
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	908 @result{} 10
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	909 globaldemo ("c")
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	910 @result{} "Global variable not found"
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	911 num2str (a)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	912 @result{} 42
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	913 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	914 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	915
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	916 @node Calling Octave Functions from Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	917 @subsection Calling Octave Functions from Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	918
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	919 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	920 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	921 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	922 calculates the definite integral by quadrature over a user supplied
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	923 function.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	924
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	925 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	926 be passed as one of
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	927
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	928 @enumerate 1
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	929 @item Function Handle
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	930
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	931 @item Anonymous Function Handle
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	932
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	933 @item Inline Function
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	934
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	935 @item String
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	936 @end enumerate
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	937
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	938 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	939 passing a function to an oct-file.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	940
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	941 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	942 @EXAMPLEFILE(funcdemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	943 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	944
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	945 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	946 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	947
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	948 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	949 @group
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	950 funcdemo (@@sin,1)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	951 @result{} 0.84147
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	952 funcdemo (@@(x) sin (x), 1)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	953 @result{} 0.84147
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	954 funcdemo (inline ("sin (x)"), 1)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	955 @result{} 0.84147
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
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	958 funcdemo (@@atan2, 1, 1)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	959 @result{} 0.78540
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	960 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	961 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	962
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	963 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	964 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	965 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	966 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	967 as demonstrated below.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	968
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	969 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	970 @group
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	971 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	972 std::string fcode = "function y = ";
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	973 fcode.append (fcn_name);
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	974 fcode.append ("(x) y = ");
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	975 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	976 fcode, "; endfunction");
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	977 @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	978 if (fcn_name.length ())
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	979 clear_function (fcn_name);
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	980 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	981 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	982
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	983 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	984 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	985 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	986 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	987 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	988
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	989 @node Calling External Code from Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	990 @subsection Calling External Code from Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	991
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	992 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	993 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	994 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	995 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	996 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	997 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	998
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	999 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1000 @group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1001 #ifdef __cplusplus
6571 24d9e0799603 [project @ 2007-04-25 03:20:17 by jwe] jwe parents: 6569 diff changeset	1002 extern "C"
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1003 @{
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1004 #endif
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1005 #include "foo.h"
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1006 #ifdef __cplusplus
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1007 @} /* end extern "C" */
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1008 #endif
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1009 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1010 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1011
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1012 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	1013 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	1014 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	1015 behavior across a number of compilers.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1016
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1017 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	1018 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	1019 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	1020 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	1021 @code{XERBLA} function, which uses @code{XSTOPX}.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1022
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1023 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	1024 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	1025 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	1026 @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	1027 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	1028 code.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1029
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1030 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	1031 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	1032 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	1033 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	1034 segmentation fault.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1035
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1036 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	1037 given in the following example, where the C++ wrapper is
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1038
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1039 @example
18437 4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix. Rik <rik@octave.org> parents: 18435 diff changeset	1040 @EXAMPLEFILE(fortrandemo.cc)
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1041 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1042
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	1043 @noindent
10791 3140cb7a05a1 Add spellchecker scripts for Octave and run spellcheck of documentation Rik <octave@nomad.inbox5.com> parents: 9906 diff changeset	1044 and the Fortran function is
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1045
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1046 @example
18437 4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix. Rik <rik@octave.org> parents: 18435 diff changeset	1047 @EXAMPLEFILE(fortransub.f)
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1048 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1049
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1050 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	1051 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	1052 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	1053 in order for the example to work.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1054
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1055 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1056 @group
18437 4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix. Rik <rik@octave.org> parents: 18435 diff changeset	1057 mkoctfile fortrandemo.cc fortransub.f
4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix. Rik <rik@octave.org> parents: 18435 diff changeset	1058 [b, s] = fortrandemo (1:3)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1059 @result{}
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1060 b = 1.00000 0.50000 0.33333
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1061 s = There are 3 values in the input vector
18437 4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix. Rik <rik@octave.org> parents: 18435 diff changeset	1062 [b, s] = fortrandemo (0:3)
4b32677b6229 Rename Fortran example files from 'fort' prefix to 'fortran' prefix. Rik <rik@octave.org> parents: 18435 diff changeset	1063 error: fortrandemo: fortransub: divide by zero
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1064 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1065 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1066
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1067 @node Allocating Local Memory in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1068 @subsection Allocating Local Memory in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1069
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1070 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	1071 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	1072 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	1073 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	1074 An example of its use is
6569 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 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1077 OCTAVE_LOCAL_BUFFER (double, tmp, len)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1078 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1079
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10828 diff changeset	1080 @noindent
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1081 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	1082 @code{len}.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1083
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1084 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	1085 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	1086
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1087 @node Input Parameter Checking in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1088 @subsection Input Parameter Checking in Oct-Files
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 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	1091 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	1092 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	1093 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	1094
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1095 The minimum requirement, as previously discussed, is to check the number
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1096 of input arguments before using them to avoid referencing a non-existent
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1097 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	1098 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	1099 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	1100 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	1101 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	1102 input parameter checking.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1103
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1104 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	1105 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	1106 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	1107 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	1108 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	1109 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	1110
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1111 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1112 @EXAMPLEFILE(paramdemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1113 @end example
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1114
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1115 @noindent
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	1116 An example of its use is:
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1117
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1118 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1119 @group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1120 paramdemo ([1, 2, NaN, Inf])
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1121 @result{} Properties of input array:
18426 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1122 includes Inf or NaN values
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1123 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	1124 includes only int, Inf or NaN values
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1125 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1126 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1127
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1128 @node Exception and Error Handling in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1129 @subsection Exception and Error Handling in Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1130
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1131 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	1132 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	1133 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	1134 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	1135 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	1136 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	1137
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1138 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1139 @group
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1140 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	1141 @{
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1142 OCTAVE_QUIT;
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1143 b.elem (i) = 2. * a.elem (i);
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1144 @}
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1145 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1146 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1147
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	1148 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	1149 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	1150 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	1151 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	1152
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	1153 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	1154 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	1155 @w{@code{OCTAVE_QUIT}}.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1156
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1157 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	1158 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	1159 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	1160 in this case. The alternative in this case is
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1161
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1162 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1163 @group
6577 f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1164 BEGIN_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE;
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1165 @dots{} some code that calls a "foreign" function @dots{}
f72d6d4b735a [project @ 2007-04-25 15:54:59 by jwe] jwe parents: 6572 diff changeset	1166 END_INTERRUPT_IMMEDIATELY_IN_FOREIGN_CODE;
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1167 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1168 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1169
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1170 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	1171 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	1172 without being deallocated. Therefore, ideally Octave itself should
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1173 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	1174 @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	1175
15684 ddc651eecf7a Fix Info index for language statements (bug #37787) Rik <rik@octave.org> parents: 14138 diff changeset	1176 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	1177 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	1178 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	1179 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	1180 example of the use of this mechanism is
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1181
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1182 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1183 @EXAMPLEFILE(unwinddemo.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1184 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1185
10828 322f43e0e170 Grammarcheck .txi documentation files. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	1186 As can be seen in the example:
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1187
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1188 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1189 @group
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	1190 unwinddemo (1, 0)
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1191 @result{} Inf
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1192 1 / 0
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1193 @result{} warning: division by zero
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1194 Inf
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1195 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1196 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1197
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1198 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	1199 @code{unwinddemo} function.
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1200
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1201 @node Documentation and Test of Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1202 @subsection Documentation and Test of Oct-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1203
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1204 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	1205 @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	1206 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	1207 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	1208 help strings within oct-files.
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1209
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1210 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	1211 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	1212 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	1213 common is illustrated in the following example,
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1214
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1215 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1216 @group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1217 DEFUN_DLD (do_what_i_want, args, nargout,
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1218 "-- texinfo --\n\
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1219 @@deftypefn @{Function File@} @{@} do_what_i_say (@@var@{n@})\n\
7081 503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	1220 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	1221 than what they requested.\n\
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1222 @@end deftypefn")
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1223 @{
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1224 @dots{}
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1225 @}
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1226 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1227 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1228
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1229 @noindent
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1230 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	1231 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	1232 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	1233 character on the line.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1234
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1235 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	1236 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	1237 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	1238 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	1239 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	1240 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	1241 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	1242 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	1243 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	1244 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	1245 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	1246
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1247 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1248 @group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1249 /*
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1250 %!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	1251 %!error (sin ())
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1252 %!error (sin (1,1))
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1253 */
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1254 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1255 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1256
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1257 @c @node Application Programming Interface for Oct-Files
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1258 @c @subsection Application Programming Interface for Oct-Files
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1259 @c
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1260 @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	1261
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1262 @node Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1263 @section Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1264 @cindex mex-files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1265 @cindex mex
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1266
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1267 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	1268 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	1269 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	1270 @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	1271 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	1272 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	1273 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	1274 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	1275 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	1276 be written with the oct-file interface previously discussed.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1277
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1278 @menu
17152 f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1279 * Getting Started with Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1280 * 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	1281 * Character Strings in Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1282 * Cell Arrays with Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1283 * Structures with Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1284 * Sparse Matrices with Mex-Files::
f2a8592b8fbd doc: Shorten some long subsection names in Manual. Rik <rik@octave.org> parents: 17097 diff changeset	1285 * Calling Other Functions in Mex-Files::
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1286 @c * Application Programming Interface for Mex-Files::
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1287 @end menu
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1288
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1289 @node Getting Started with Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1290 @subsection Getting Started with Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1291
11479 746609dd54fd Remove Matlab euphemisms in docs and use @file macro for filenames Jordi Gutiérrez Hermoso <jordigh@gmail.com> parents: 10846 diff changeset	1292 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	1293 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	1294 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	1295 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	1296 Compiled mex-files have the extension @file{.mex}.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1297
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1298 @DOCSTRING(mex)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1299
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1300 @DOCSTRING(mexext)
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1301
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1302 Consider the following short example:
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1303
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1304 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1305 @group
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1306 @EXAMPLEFILE(myhello.c)
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1307 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1308 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1309
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1310 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	1311 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	1312 @sc{matlab} is that the header file @qcode{"matrix.h"} is implicitly included
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	1313 through the inclusion of @qcode{"mex.h"}. This is necessary to avoid a conflict
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	1314 with the Octave file @qcode{"Matrix.h"} for operating systems and compilers that
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1315 don't distinguish between filenames in upper and lower case.
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1316
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1317 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	1318 function takes four arguments:
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1319
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1320 @enumerate 1
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1321 @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	1322
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1323 @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	1324
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1325 @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	1326
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1327 @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	1328 @end enumerate
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1329
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1330 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	1331 @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	1332 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	1333 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	1334 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	1335
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1336 @example
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1337 mkoctfile --mex myhello.c
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1338 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1339
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1340 @noindent
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1341 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	1342 Octave as
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1343
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1344 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1345 @group
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1346 myhello (1,2,3)
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1347 @result{} Hello, World!
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1348 @result{} I have 3 inputs and 0 outputs
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1349 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1350 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1351
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1352 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	1353 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	1354 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	1355 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	1356 contain the text
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 @example
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1359 %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	1360 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1361
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1362 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	1363 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	1364 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	1365 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	1366
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1367 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	1368 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	1369 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	1370 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	1371
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1372 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1373 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1374 @EXAMPLEFILE(myfunc.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1375 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1376 @end example
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1377
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1378 @noindent
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1379 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	1380
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1381 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1382 @group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1383 mkoctfile --mex myfunc.c
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1384 ln -s myfunc.mex myfunc2.mex
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1385 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1386 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1387
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1388 @noindent
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1389 then as can be seen by
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1390
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1391 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1392 @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	1393 myfunc ()
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1394 @result{} You called function: myfunc
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1395 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	1396 myfunc2 ()
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1397 @result{} You called function: myfunc2
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1398 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1399 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1400
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1401 @noindent
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1402 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	1403 name.
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1404
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1405 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	1406 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	1407 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	1408
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1409 @node Working with Matrices and Arrays in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1410 @subsection Working with Matrices and Arrays in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1411
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1412 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	1413 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	1414 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	1415 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	1416 more specialized types.
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 @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	1419 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	1420 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	1421 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	1422 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	1423 @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	1424 and the generic @code{mxCreateNumericArray}.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1425
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1426 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	1427 @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	1428 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	1429 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	1430 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	1431 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	1432 on all matrix types. For example:
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1433
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1434 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1435 @group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1436 mxArray *m;
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1437 mwSize *dims;
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1438 UINT32_T *pr;
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1439
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1440 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	1441 dims[0] = 2; dims[1] = 2;
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1442 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	1443 pr = (UINT32_T *) mxGetData (m);
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1444 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1445 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1446
9080 ec41eabf4499 Cleanup documentation files dynamic.texi, testfun.texi, tips.texi Rik <rdrider0-list@yahoo.com> parents: 9038 diff changeset	1447 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	1448 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	1449 to by the argument of @code{mxSetPr}.
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1450
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1451 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	1452 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	1453 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	1454 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	1455 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	1456 indexing into arrays.
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1457
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1458 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	1459 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	1460
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1461 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1462 @EXAMPLEFILE(mypow2.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1463 @end example
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1464
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1465 @noindent
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1466 with an example of its use
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1467
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1468 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1469 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1470 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	1471 all (b.^2 == mypow2 (b))
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1472 @result{} 1
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1473 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1474 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1475
7096 81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe] jwe parents: 7081 diff changeset	1476 The example above uses the functions @code{mxGetDimensions},
81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe] jwe parents: 7081 diff changeset	1477 @code{mxGetNumberOfElements}, and @code{mxGetNumberOfDimensions} to work
81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe] jwe parents: 7081 diff changeset	1478 with the dimensions of multi-dimensional arrays. The functions
81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe] jwe parents: 7081 diff changeset	1479 @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	1480 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	1481
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1482 @node Character Strings in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1483 @subsection Character Strings in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1484
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1485 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	1486 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	1487 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	1488 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	1489 file @file{mystring.c}, as shown below.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1490
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1491 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1492 @EXAMPLEFILE(mystring.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1493 @end example
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1494
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1495 @noindent
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1496 An example of its expected output is
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1497
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1498 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1499 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1500 mystring (["First String"; "Second String"])
18426 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1501 @result{} Second String
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1502 First String
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1503 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1504 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1505
7096 81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe] jwe parents: 7081 diff changeset	1506 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	1507 @code{mxCreateString}, @code{mxArrayToString}, and
81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe] jwe parents: 7081 diff changeset	1508 @code{mxCreateCharMatrixFromStrings}. In a mex-file, a character string
81bed50b9feb [project @ 2007-11-02 16:13:43 by jwe] jwe parents: 7081 diff changeset	1509 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	1510 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	1511 consecutive in any case.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1512
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1513 @node Cell Arrays with Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1514 @subsection Cell Arrays with Mex-Files
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1515
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1516 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	1517 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	1518 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	1519 as shown below.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1520
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1521 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1522 @EXAMPLEFILE(mycell.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1523 @end example
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1524
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1525 @noindent
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1526 The output is identical to the oct-file version as well.
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1527
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1528 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1529 @group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1530 [b1, b2, b3] = mycell (@{1, [1, 2], "test"@})
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1531 @result{}
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1532 b1 = 1
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1533 b2 =
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1534
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1535 1 2
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1536
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1537 b3 = test
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1538 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1539 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1540
9080 ec41eabf4499 Cleanup documentation files dynamic.texi, testfun.texi, tips.texi Rik <rdrider0-list@yahoo.com> parents: 9038 diff changeset	1541 Note in the example the use of the @code{mxDuplicateArray} function. This
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1542 is needed as the @code{mxArray} pointer returned by @code{mxGetCell}
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1543 might be deallocated. The inverse function to @code{mxGetCell}, used for
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1544 setting Cell values, is @code{mxSetCell} and is defined as
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1545
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1546 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1547 void mxSetCell (mxArray ptr, int idx, mxArray val);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1548 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1549
7007 6304d9ea0a30 [project @ 2007-10-11 16:26:36 by jwe] jwe parents: 7001 diff changeset	1550 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	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 @group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1554 mxArray mxCreateCellArray (int ndims, const int dims);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1555 mxArray *mxCreateCellMatrix (int m, int n);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1556 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1557 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1558
6572 8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	1559 @node Structures with Mex-Files
8e7148b84b59 [project @ 2007-04-25 04:13:44 by jwe] jwe parents: 6571 diff changeset	1560 @subsection Structures with Mex-Files
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1561
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1562 The basic function to create a structure in a mex-file is
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1563 @code{mxCreateStructMatrix} which creates a structure array with a two
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1564 dimensional matrix, or @code{mxCreateStructArray}.
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1565
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1566 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1567 @group
7081 503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	1568 mxArray mxCreateStructArray (int ndims, int dims,
503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	1569 int num_keys,
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1570 const char **keys);
7081 503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	1571 mxArray *mxCreateStructMatrix (int rows, int cols,
503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	1572 int num_keys,
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1573 const char **keys);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1574 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1575 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1576
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1577 Accessing the fields of the structure can then be performed with
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1578 @code{mxGetField} and @code{mxSetField} or alternatively with the
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1579 @code{mxGetFieldByNumber} and @code{mxSetFieldByNumber} functions.
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1580
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1581 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1582 @group
7081 503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	1583 mxArray mxGetField (const mxArray ptr, mwIndex index,
503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	1584 const char *key);
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1585 mxArray mxGetFieldByNumber (const mxArray ptr,
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1586 mwIndex index, int key_num);
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1587 void mxSetField (mxArray *ptr, mwIndex index,
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1588 const char key, mxArray val);
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1589 void mxSetFieldByNumber (mxArray *ptr, mwIndex index,
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1590 int key_num, mxArray *val);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1591 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1592 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1593
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1594 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	1595 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	1596 mex-files directly include an @code{index} over the elements of the
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1597 arrays of elements per @code{field}; Whereas, the oct-file structure
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1598 includes a Cell Array per field of the structure.
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1599
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1600 An example that demonstrates the use of structures in a mex-file can be
be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1601 found in the file @file{mystruct.c} shown below.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1602
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1603 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1604 @EXAMPLEFILE(mystruct.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1605 @end example
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1606
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1607 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	1608
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1609 @example
7081 503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	1610 a(1).f1 = "f11"; a(1).f2 = "f12";
503001863427 [project @ 2007-10-31 01:08:14 by jwe] jwe parents: 7018 diff changeset	1611 a(2).f1 = "f21"; a(2).f2 = "f22";
18426 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1612 b = mystruct (a);
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1613 @result{} field f1(0) = f11
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1614 field f1(1) = f21
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1615 field f2(0) = f12
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1616 field f2(1) = f22
18426 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1617 b
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1618 @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	1619
18426 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1620 this
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1621 that
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 17152 diff changeset	1622
18426 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1623 b(3)
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1624 @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	1625
18426 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1626 this = this3
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1627 that = that3
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1628 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1629
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1630 @node Sparse Matrices with Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1631 @subsection Sparse Matrices with Mex-Files
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1632
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1633 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	1634 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	1635 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	1636 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	1637
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1638 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	1639 @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	1640 @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	1641
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1642 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1643 @group
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1644 mwIndex mxGetIr (const mxArray ptr);
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1645 mwIndex mxGetJc (const mxArray ptr);
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1646 mwSize mxGetNzmax (const mxArray *ptr);
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1647
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1648 void mxSetIr (mxArray ptr, mwIndex ir);
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1649 void mxSetJc (mxArray ptr, mwIndex jc);
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1650 void mxSetNzmax (mxArray *ptr, mwSize nzmax);
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1651 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1652 @end example
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1653
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1654 @noindent
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1655 @code{mxGetNzmax} gets the maximum number of elements that can be stored
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1656 in the sparse matrix. This is not necessarily the number of non-zero
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1657 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	1658 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	1659 difference between consecutive values of the array returned by
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1660 @code{mxGetJc} define the number of non-zero elements in each column of
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1661 the sparse matrix. Therefore,
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1662
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1663 @example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1664 @group
6686 2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1665 mwSize nz, n;
2aad75fcc93a [project @ 2007-06-03 20:58:28 by dbateman] dbateman parents: 6606 diff changeset	1666 mwIndex *Jc;
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1667 mxArray *m;
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1668 @dots{}
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1669 n = mxGetN (m);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1670 Jc = mxGetJc (m);
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1671 nz = Jc[n];
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1672 @end group
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1673 @end example
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1674
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1675 @noindent
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1676 returns the actual number of non-zero elements stored in the matrix in
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1677 @code{nz}. As the arrays returned by @code{mxGetPr} and @code{mxGetPi}
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1678 only contain the non-zero values of the matrix, we also need a pointer
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1679 to the rows of the non-zero elements, and this is given by
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1680 @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	1681 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	1682
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1683 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1684 @EXAMPLEFILE(mysparse.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1685 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1686
18426 adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1687 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	1688
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1689 @example
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1690 @group
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1691 sm = sparse ([1, 0; 0, pi]);
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1692 mysparse (sm)
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1693 @result{}
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1694 Matrix is 2-by-2 real sparse matrix with 2 elements
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1695 last non-zero element (2, 2) = 3.14159
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1696 @end group
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1697 @end example
adb7c7e6a4a1 doc: Re-write bits of External Code Interface chapter. Rik <rik@octave.org> parents: 18075 diff changeset	1698
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1699 @node Calling Other Functions in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1700 @subsection Calling Other Functions in Mex-Files
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1701
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1702 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	1703 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	1704 can be see in the example below.
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1705
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1706 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1707 @EXAMPLEFILE(myfeval.c)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1708 @end example
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1709
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1710 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	1711 @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	1712
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1713 @example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1714 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	1715 a = myfeval ("sin", 1)
18435 d1e16bdb3958 myfeval.c: Fix segfault in mex example code. Rik <rik@octave.org> parents: 18426 diff changeset	1716 @result{} Starting file myfeval.mex
d1e16bdb3958 myfeval.c: Fix segfault in mex example code. Rik <rik@octave.org> parents: 18426 diff changeset	1717 I have 2 inputs and 1 outputs
d1e16bdb3958 myfeval.c: Fix segfault in mex example code. Rik <rik@octave.org> parents: 18426 diff changeset	1718 I'm going to call the interpreter function sin
d1e16bdb3958 myfeval.c: Fix segfault in mex example code. Rik <rik@octave.org> parents: 18426 diff changeset	1719 a = 0.84147
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1720 @end group
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1721 @end example
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1722
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1723 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	1724 within a mex-file.
d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1725
6593 3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1726 @c @node Application Programming Interface for Mex-Files
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1727 @c @subsection Application Programming Interface for Mex-Files
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1728 @c
3da1f4a41455 [project @ 2007-04-27 08:08:19 by dbateman] dbateman parents: 6583 diff changeset	1729 @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	1730
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1731 @node Standalone Programs
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1732 @section Standalone Programs
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1733
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1734 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	1735 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	1736 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	1737 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	1738 @file{liboctave.so}.
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1739
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1740 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1741 @EXAMPLEFILE(standalone.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1742 @end example
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1743
6580 d2bb3b8a8d20 [project @ 2007-04-25 22:19:03 by dbateman] dbateman parents: 6578 diff changeset	1744 @noindent
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1745 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	1746 command like
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1747
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1748 @example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1749 @group
8097 804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1750 $ 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	1751 $ ./standalone
6569 81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1752 Hello Octave world!
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1753 11 12
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1754 21 22
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 @end group
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1757 @end example
81a8ab62b2b9 [project @ 2007-04-24 23:01:29 by jwe] jwe parents: diff changeset	1758
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1759 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	1760 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	1761 allows the Octave math libraries to be used by an application. It does
18602 f51c1498b9f3 doc: Replace "builtin" with "built-in" for consistency and correctness. Rik <rik@octave.org> parents: 18437 diff changeset	1762 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	1763 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	1764 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	1765 seen in the code
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1766
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1767 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1768 @EXAMPLEFILE(embedded.cc)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1769 @end example
8097 804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1770
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1771 @noindent
16867 be41c30bcb44 Re-write documentation and all examples of dynamically linked functions. Rik <rik@octave.org> parents: 16483 diff changeset	1772 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	1773
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1774 @example
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1775 @group
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1776 $ 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	1777 $ ./embedded
16483 fcf1b0b52083 Use a better example of gcd() in embedded.cc Rik <rik@octave.org> parents: 16482 diff changeset	1778 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	1779 $
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1780 @end group
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1781 @end example
804c60f92fb1 Add explanationation of initializing the interpreter in a standalone program David Bateman <dbateman@free.fr> parents: 7354 diff changeset	1782
18602 f51c1498b9f3 doc: Replace "builtin" with "built-in" for consistency and correctness. Rik <rik@octave.org> parents: 18437 diff changeset	1783 It is worth noting that, if only built-in functions are to be called from
17949 3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1784 a C++ standalone program, then it does not need to initialize the
18602 f51c1498b9f3 doc: Replace "builtin" with "built-in" for consistency and correctness. Rik <rik@octave.org> parents: 18437 diff changeset	1785 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	1786 function named @code{function_name} in the interpreter, there will be
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1787 a C++ function named @code{Ffunction_name} (note the prepended capital
18602 f51c1498b9f3 doc: Replace "builtin" with "built-in" for consistency and correctness. Rik <rik@octave.org> parents: 18437 diff changeset	1788 @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	1789 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	1790 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	1791 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	1792 won't be implemented as a .m file or as a dynamically linked function in the
18602 f51c1498b9f3 doc: Replace "builtin" with "built-in" for consistency and correctness. Rik <rik@octave.org> parents: 18437 diff changeset	1793 future. An example of how to call built-in functions from C++ can be seen in the
18075 24759ac2b8cb doc: Periodic spellcheck of documentation Rik <rik@octave.org> parents: 17949 diff changeset	1794 code
17949 3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1795
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1796 @example
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1797 @EXAMPLEFILE(standalonebuiltin.cc)
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1798 @end example
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1799
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1800 @noindent
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1801 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	1802
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1803 @example
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1804 @group
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1805 $ mkoctfile --link-stand-alone standalonebuiltin.cc -o standalonebuiltin
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1806 $ ./standalonebuiltin
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1807 This is a matrix:
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1808 11 12
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1809 21 22
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 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	1812 34.4952
18435 d1e16bdb3958 myfeval.c: Fix segfault in mex example code. Rik <rik@octave.org> parents: 18426 diff changeset	1813 $
17949 3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1814 @end group
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1815 @end example
3341d2f1e5db Document calling DEFUN functions in C++. Carlo de Falco <cdf@users.sourceforge.net> parents: 17744 diff changeset	1816

Mercurial > hg > octave-nkf

annotate doc/interpreter/external.txi @ 18602:f51c1498b9f3 stable