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

annotate doc/interpreter/oop.txi @ 9906:8d20fb66a0dc

more automake fixes

author	John W. Eaton <jwe@octave.org>
date	Thu, 03 Dec 2009 15:39:20 -0500
parents	09da0bd91412
children	3140cb7a05a1

rev	line source
9245 16f53d29049f update copyright notices John W. Eaton <jwe@octave.org> parents: 9209 diff changeset	1 @c Copyright (C) 2008, 2009 David Bateman
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	2 @c Copyright (C) 2009 VZLU Prague
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	3 @c
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	4 @c This file is part of Octave.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	5 @c
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	6 @c Octave is free software; you can redistribute it and/or modify it
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	7 @c under the terms of the GNU General Public License as published by the
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	8 @c Free Software Foundation; either version 3 of the License, or (at
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	9 @c your option) any later version.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	10 @c
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	11 @c Octave is distributed in the hope that it will be useful, but WITHOUT
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	12 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	13 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	14 @c for more details.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	15 @c
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	16 @c You should have received a copy of the GNU General Public License
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	17 @c along with Octave; see the file COPYING. If not, see
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	18 @c <http://www.gnu.org/licenses/>.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	19
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	20 @c FIXME
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	21 @c For now can't include "@" character in the path name, and so name
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	22 @c the example directory without the "@"!!
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	23
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	24 @node Object Oriented Programming
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	25 @chapter Object Oriented Programming
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	26
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	27 Octave includes the capability to include user classes, including the
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	28 features of operator and function overloading. Equally a user class
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	29 can be used to encapsulate certain properties of the class so that
8347 fa78cb8d8a5c corrections for typos Brian Gough<bjg@network-theory.co.uk> parents: 8295 diff changeset	30 they cannot be altered accidentally and can be set up to address the
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	31 issue of class precedence in mixed class operations.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	32
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	33 This chapter discussions the means of constructing a user class with
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	34 the example of a polynomial class, how to query and set the properties
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	35 of this class, together with the means to overload operators and
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	36 functions.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	37
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	38 @menu
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	39 * Creating a Class::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	40 * Manipulating Classes::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	41 * Indexing Objects::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	42 * Overloading Objects::
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	43 * Inheritance and Aggregation::
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	44 @end menu
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	45
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	46 @node Creating a Class
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	47 @section Creating a Class
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	48
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	49 We use in the following text a polynomial class to demonstrate the use
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	50 of object oriented programming within Octave. This class was chosen as
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	51 it is simple, and so doesn't distract unnecessarily from the
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	52 discussion of the programming features of Octave. However, even still
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	53 a small understand of the polynomial class itself is necessary to
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	54 fully grasp the techniques described.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	55
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	56 The polynomial class is used to represent polynomials of the form
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	57
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	58 @example
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	59 @group
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	60 @tex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	61 $a_0 + a_1 x + a_2 x^2 + \ldots a_n x^n$
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	62 @end tex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	63 @ifnottex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	64 a0 + a1 * x + a2 * x^2 + @dots{} + an * x^n
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	65 @end ifnottex
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	66 @end group
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	67 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	68
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	69 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	70 where
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	71 @tex
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	72 $a_0$, $a_1$, etc. are elements of $\Re$.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	73 @end tex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	74 @ifnottex
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	75 a0, a1, etc. are real scalars.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	76 @end ifnottex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	77 Thus the polynomial can be represented by a vector
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	78
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	79 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	80 a = [a0, a1, a2, @dots{}, an];
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	81 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	82
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	83 We therefore now have sufficient information about the requirements of
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	84 the class constructor for our polynomial class to write it. All object
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	85 oriented classes in Octave, must be contained with a directory taking
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	86 the name of the class, prepended with the @@ symbol. For example, with
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	87 our polynomial class, we would place the methods defining the class in
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	88 the @@polynomial directory.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	89
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	90 The constructor of the class, must have the name of the class itself
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	91 and so in our example the constructor with have the name
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	92 @file{@@polynomial/polynomial.m}. Also ideally when the constructor is
17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	93 called with no arguments to should return a value object. So for example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	94 our polynomial might look like
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	95
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	96 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	97 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	98 @EXAMPLEFILE(@polynomial/polynomial.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	99 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	100 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	101
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	102 Note that the return value of the constructor must be the output of
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	103 the @code{class} function called with the first argument being a
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	104 structure and the second argument being the class name. An example of
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	105 the call to this constructor function is then
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	106
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	107 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	108 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	109 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	110
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	111 Note that methods of a class can be documented. The help for the
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	112 constructor itself can be obtained with the constructor name, that is
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	113 for the polynomial constructor @code{help polynomial} will return the
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	114 help string. Also the help can be obtained by restricting the search
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	115 for the help to a particular class, for example @code{help
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	116 @@polynomial/polynomial}. This second method is the only means of
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	117 getting help for the overloaded methods and functions of the class.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	118
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	119 The same is true for other Octave functions that take a function name
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	120 as an argument. For example @code{type @@polynomial/display} will
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	121 print the code of the display method of the polynomial class to the
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	122 screen, and @code{dbstop @@polynomial/display} will set a breakpoint
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	123 at the first executable line of the display method of the polynomial
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	124 class.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	125
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	126 To check where a variable is a user class, the @code{isobject} and
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	127 @code{isa} functions can be used. for example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	128
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	129 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	130 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	131 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	132 isobject (p)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	133 @result{} 1
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	134 isa (p, "polynomial")
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	135 @result{} 1
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	136 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	137 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	138
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	139 @DOCSTRING(isobject)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	140
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	141 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	142 The available methods of a class can be displayed with the
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	143 @code{methods} function.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	144
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	145 @DOCSTRING(methods)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	146
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	147 @noindent
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	148 To inquire whether a particular method is available to a user class, the
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	149 @code{ismethod} function can be used.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	150
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	151 @DOCSTRING(ismethod)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	152
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	153 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	154 For example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	155
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	156 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	157 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	158 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	159 ismethod (p, "roots")
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	160 @result{} 1
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	161 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	162 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	163
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	164 @node Manipulating Classes
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	165 @section Manipulating Classes
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	166
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	167 There are a number of basic classes methods that can be defined to allow
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	168 the contents of the classes to be queried and set. The most basic of
17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	169 these is the @code{display} method. The @code{display} method is used
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	170 by Octave when displaying a class on the screen, due to an expression
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	171 that is not terminated with a semicolon. If this method is not defined,
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	172 then Octave will printed nothing when displaying the contents of a class.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	173
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	174 @DOCSTRING(display)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	175
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	176 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	177 An example of a display method for the polynomial class might be
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	178
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	179 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	180 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	181 @EXAMPLEFILE(@polynomial/display.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	182 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	183 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	184
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	185 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	186 Note that in the display method, it makes sense to start the method
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	187 with the line @code{fprintf("%s =", inputname(1))} to be consistent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	188 with the rest of Octave and print the variable name to be displayed
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	189 when displaying the class.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	190
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	191 To be consistent with the Octave graphic handle classes, a class
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	192 should also define the @code{get} and @code{set} methods. The
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	193 @code{get} method should accept one or two arguments, and given one
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	194 argument of the appropriate class it should return a structure with
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	195 all of the properties of the class. For example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	196
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	197 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	198 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	199 @EXAMPLEFILE(@polynomial/get.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	200 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	201 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	202
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	203 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	204 Similarly, the @code{set} method should taken as its first argument an
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	205 object to modify, and then take property/value pairs to be modified.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	206
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	207 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	208 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	209 @EXAMPLEFILE(@polynomial/set.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	210 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	211 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	212
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	213 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	214 Note that as Octave does not implement pass by reference, than the
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	215 modified object is the return value of the @code{set} method and it
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	216 must be called like
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	217
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	218 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	219 p = set (p, "a", [1, 0, 0, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	220 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	221
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	222 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	223 Also the @code{set} method makes use of the @code{subsasgn} method of
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	224 the class, and this method must be defined. The @code{subsasgn} method
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	225 is discussed in the next section.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	226
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	227 Finally, user classes can be considered as a special type of a
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	228 structure, and so they can be saved to a file in the same manner as a
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	229 structure. For example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	230
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	231 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	232 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	233 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	234 save userclass.mat p
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	235 clear p
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	236 load userclass.mat
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	237 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	238 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	239
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	240 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	241 All of the file formats supported by @code{save} and @code{load} are
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	242 supported. In certain circumstances, a user class might either contain
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	243 a field that it makes no sense to save or a field that needs to be
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	244 initialized before it is saved. This can be done with the
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	245 @code{saveobj} method of the class
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	246
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	247 @DOCSTRING(saveobj)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	248
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	249 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	250 @code{saveobj} is called just prior to saving the class to a
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	251 file. Likely, the @code{loadobj} method is called just after a class
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	252 is loaded from a file, and can be used to ensure that any removed
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	253 fields are reinserted into the user object.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	254
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	255 @DOCSTRING(loadobj)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	256
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	257 @node Indexing Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	258 @section Indexing Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	259
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	260 @menu
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	261 * Defining Indexing And Indexed Assignment::
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	262 * Indexed Assignment Optimization::
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	263 @end menu
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	264
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	265 @node Defining Indexing And Indexed Assignment
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	266 @subsection Defining Indexing And Indexed Assignment
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	267
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	268 Objects can be indexed with parentheses, either like
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	269 @code{@var{a} (@var{idx})} or like @code{@var{a} @{@var{idx}@}}, or even
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	270 like @code{@var{a} (@var{idx}).@var{field}}. However, it is up to the user
17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	271 to decide what this indexing actually means. In the case of our polynomial
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	272 class @code{@var{p} (@var{n})} might mean either the coefficient of the
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	273 @var{n}-th power of the polynomial, or it might be the evaluation of the
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	274 polynomial at @var{n}. The meaning of this subscripted referencing is
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	275 determined by the @code{subsref} method.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	276
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	277 @DOCSTRING(subsref)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	278
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	279 For example we might decide that indexing with "()" evaluates the
9285 226f6d001ee2 further improve the polynomial example, fix indexing Jaroslav Hajek <highegg@gmail.com> parents: 9251 diff changeset	280 polynomial and indexing with "@{@}" returns the @var{n}-th coefficient (of @var{n}-th power).
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	281 In this case the @code{subsref} method of our polynomial class might look like
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	282
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	283 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	284 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	285 @EXAMPLEFILE(@polynomial/subsref.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	286 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	287 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	288
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	289 The equivalent functionality for subscripted assignments uses the
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	290 @code{subsasgn} method.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	291
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	292 @DOCSTRING(subsasgn)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	293
9285 226f6d001ee2 further improve the polynomial example, fix indexing Jaroslav Hajek <highegg@gmail.com> parents: 9251 diff changeset	294 Note that the @code{subsref} and @code{subsasgn} methods always receive the
226f6d001ee2 further improve the polynomial example, fix indexing Jaroslav Hajek <highegg@gmail.com> parents: 9251 diff changeset	295 whole index chain, while they usually handle only the first element. It is the
226f6d001ee2 further improve the polynomial example, fix indexing Jaroslav Hajek <highegg@gmail.com> parents: 9251 diff changeset	296 responsibility of these methods to handle the rest of the chain (if needed),
226f6d001ee2 further improve the polynomial example, fix indexing Jaroslav Hajek <highegg@gmail.com> parents: 9251 diff changeset	297 usually by forwarding it again to @code{subsref} or @code{subsasgn}.
226f6d001ee2 further improve the polynomial example, fix indexing Jaroslav Hajek <highegg@gmail.com> parents: 9251 diff changeset	298
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	299 If you wish to use the @code{end} keyword in subscripted expressions
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	300 of an object, then the user needs to define the @code{end} method for
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	301 the class.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	302
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	303 @DOCSTRING(end)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	304
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	305 For example the @code{end} method for our polynomial class might look like
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	306
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	307 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	308 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	309 @EXAMPLEFILE(@polynomial/end.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	310 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	311 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	312
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	313 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	314 which is a fairly generic @code{end} method that has a behavior similar to
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	315 the @code{end} keyword for Octave Array classes. It can then be used for
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	316 example like
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	317
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	318 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	319 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	320 p = polynomial([1,2,3,4]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	321 p(end-1)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	322 @result{} 3
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	323 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	324 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	325
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	326 Objects can also be used as the index in a subscripted expression themselves
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	327 and this is controlled with the @code{subsindex} function.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	328
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	329 @DOCSTRING(subsindex)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	330
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	331 Finally, objects can equally be used like ranges, using the @code{colon}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	332 method
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	333
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	334 @DOCSTRING(colon)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	335
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	336 @node Indexed Assignment Optimization
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	337 @subsection Indexed Assignment Optimization
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	338
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	339 Octave's ubiquitous lazily-copied pass-by-value semantics implies
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	340 a problem for performance of user-defined subsasgn methods. Imagine
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	341 a call to subsasgn:
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	342
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	343 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	344 @group
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	345 ss = substruct ("()",@{1@});
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	346 x = subsasgn (x, ss, 1);
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	347 @end group
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	348 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	349
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	350 and the corresponding method looking like this:
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	351
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	352 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	353 @group
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	354 function x = subsasgn (x, ss, val)
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	355 @dots{}
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	356 x.myfield(ss.subs@{1@}) = val;
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	357 endfunction
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	358 @end group
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	359 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	360
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	361 The problem is that on entry to the subsasgn method, @code{x} is still
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	362 referenced from the caller's scope, which means that the method will
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	363 first need to unshare (copy) @code{x} and @code{x.myfield} before performing
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	364 the assignment. Upon completing the call, unless an error occurs,
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	365 the result is immediately assigned to @code{x} in the caller's scope,
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	366 so that the previous value of @code{x.myfield} is forgotten. Hence, the
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	367 Octave language implies a copy of N elements (N being the size of
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	368 @code{x.myfield}), where modifying just a single element would actually
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	369 suffice, i.e., degrades a constant-time operation to linear-time one.
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	370 This may be a real problem for user classes that intrinsically store large
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	371 arrays.
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	372
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	373 To partially solve the problem, Octave uses a special optimization for
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	374 user-defined subsasgn methods coded as m-files. When the method
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	375 gets called as a result of the built-in assignment syntax (not direct subsasgn
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	376 call as shown above), i.e.
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	377
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	378 @example
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	379 x(1) = 1;
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	380 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	381
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	382 @b{AND} if the subsasgn method is declared with identical input and output argument,
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	383 like in the example above, then Octave will ignore the copy of @code{x} inside
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	384 the caller's scope; therefore, any changes made to @code{x} during the method
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	385 execution will directly affect the caller's copy as well.
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	386 This allows, for instance, defining a polynomial class where modifying a single
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	387 element takes constant time.
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	388
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	389 It is important to understand the implications that this optimization brings.
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	390 Since no extra copy of @code{x} in the caller's scope will exist, it is @i{solely}
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	391 the callee's responsibility to not leave @code{x} in an invalid state if an error
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	392 occurs throughout the execution. Also, if the method partially changes @code{x}
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	393 and then errors out, the changes @i{will} affect @code{x} in the caller's scope.
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	394 Deleting or completely replacing @code{x} inside subsasgn will not do anything,
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	395 however, only indexed assignments matter.
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	396
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	397 Since this optimization may change the way code works (especially if badly written),
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	398 a built-in variable @code{optimize_subsasgn_calls} is provided to control it.
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	399 It is on by default.
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	400 Another option to avoid the effect is to declare subsasgn methods with different
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	401 output and input arguments, like this:
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	402
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	403 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	404 @group
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	405 function y = subsasgn (x, ss, val)
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	406 @dots{}
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	407 endfunction
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	408 @end group
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	409 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	410
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	411 @node Overloading Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	412 @section Overloading Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	413
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	414 @menu
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	415 * Function Overloading::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	416 * Operator Overloading::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	417 * Precedence of Objects::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	418 @end menu
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	419
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	420 @node Function Overloading
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	421 @subsection Function Overloading
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	422
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	423 Any Octave function can be overloaded, and allows a object specific
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	424 version of this function to be called as needed. A pertinent example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	425 for our polynomial class might be to overload the @code{polyval} function
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	426 like
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	427
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	428 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	429 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	430 @EXAMPLEFILE(@polynomial/polyval.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	431 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	432 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	433
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	434 This function just hands off the work to the normal Octave @code{polyval}
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	435 function. Another interesting example for an overloaded function for our
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	436 polynomial class is the @code{plot} function.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	437
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	438 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	439 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	440 @EXAMPLEFILE(@polynomial/plot.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	441 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	442 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	443
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	444 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	445 which allows polynomials to be plotted in the domain near the region
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	446 of the roots of the polynomial.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	447
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	448 Functions that are of particular interest to be overloaded are the class
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	449 conversion functions such as @code{double}. Overloading these functions
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	450 allows the @code{cast} function to work with the user class and can aid
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	451 in the use of methods of other classes with the user class. An example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	452 @code{double} function for our polynomial class might look like.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	453
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	454 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	455 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	456 @EXAMPLEFILE(@polynomial/double.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	457 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	458 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	459
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	460 @node Operator Overloading
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	461 @subsection Operator Overloading
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	462
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	463 @float Table,tab:overload_ops
8286 6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	464
6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	465 @anchor{doc-rdivide} @anchor{doc-plus} @anchor{doc-minus} @anchor{doc-uminus}
6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	466 @anchor{doc-uplus} @anchor{doc-times} @anchor{doc-mtimes} @anchor{doc-mrdivide}
6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	467 @anchor{doc-ldivide} @anchor{doc-mldivide} @anchor{doc-power}
6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	468 @anchor{doc-mpower} @anchor{doc-lt} @anchor{doc-le} @anchor{doc-gt}
6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	469 @anchor{doc-ge} @anchor{doc-eq} @anchor{doc-ne} @anchor{doc-and}
6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	470 @anchor{doc-or} @anchor{doc-not} @anchor{doc-ctranspose} @anchor{doc-transpose}
6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	471
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	472 @tex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	473 \vskip 6pt
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	474 {\hbox to \hsize {\hfill\vbox{\offinterlineskip \tabskip=0pt
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	475 \halign{
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	476 \vrule height2.0ex depth1.ex width 0.6pt #\tabskip=0.3em &
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	477 # \hfil & \vrule # & # \hfil & \vrule # & # \hfil & # \vrule
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	478 width 0.6pt \tabskip=0pt\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	479 \noalign{\hrule height 0.6pt}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	480 & Operation && Method && Description &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	481 \noalign{\hrule}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	482 & $a + b$ && plus (a, b) && Binary addition operator&\cr
8295 16819ca24fa5 fix typo in docs John W. Eaton <jwe@octave.org> parents: 8286 diff changeset	483 & $a - b$ && minus (a, b) && Binary subtraction operator&\cr
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	484 & $+ a$ && uplus (a) && Unary addition operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	485 & $- a$ && uminus (a) && Unary subtraction operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	486 & $a .* b$ && times (a, b) && Element-wise multiplication operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	487 & $a * b$ && mtimes (a, b) && Matrix multiplication operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	488 & $a ./ b$ && rdivide (a, b) && Element-wise right division operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	489 & $a / b$ && mrdivide (a, b) && Matrix right division operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	490 & $a .\backslash b$ && ldivide (a, b) && Element-wise left division operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	491 & $a \backslash b$ && mldivide (a, b) && Matrix left division operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	492 & $a .\hat b$ && power (a, b) && Element-wise power operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	493 & $a \hat b$ && mpower (a, b) && Matrix power operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	494 & $a < b$ && lt (a, b) && Less than operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	495 & $a <= b$ && le (a, b) && Less than or equal to operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	496 & $a > b$ && gt (a, b) && Greater than operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	497 & $a >= b$ && ge (a, b) && Greater than or equal to operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	498 & $a == b$ && eq (a, b) && Equal to operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	499 & $a != b$ && ne (a, b) && Not equal to operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	500 & $a \& b$ && and (a, b) && Logical and operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	501 & $a \| b$ && or (a, b) && Logical or operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	502 & $! b$ && not (a) && Logical not operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	503 & $a'$ && ctranspose (a) && Complex conjugate transpose operator &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	504 & $a.'$ && transpose (a) && Transpose operator &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	505 & $a : b$ && colon (a, b) && Two element range operator &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	506 & $a : b : c$ && colon (a, b, c) && Three element range operator &\cr
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	507 & $[a, b]$ && horzcat (a, b) && Horizontal concatenation operator &\cr
17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	508 & $[a; b]$ && vertcat (a, b) && Vertical concatenation operator &\cr
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	509 & $a(s_1, \ldots, s_n)$ && subsref (a, s) && Subscripted reference &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	510 & $a(s_1, \ldots, s_n) = b$ && subsasgn (a, s, b) && Subscripted assignment &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	511 & $b (a)$ && subsindex (a) && Convert to zero-based index &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	512 & {\it display} && display (a) && Commandline display function &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	513 \noalign{\hrule height 0.6pt}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	514 }}\hfill}}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	515 @end tex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	516 @ifnottex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	517 @multitable @columnfractions .1 .20 .20 .40 .1
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	518 @item @tab Operation @tab Method @tab Description @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	519 @item @tab a + b @tab plus (a, b) @tab Binary addition @tab
8295 16819ca24fa5 fix typo in docs John W. Eaton <jwe@octave.org> parents: 8286 diff changeset	520 @item @tab a - b$ @tab minus (a, b) @tab Binary subtraction operator @tab
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	521 @item @tab + a$ @tab uplus (a) @tab Unary addition operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	522 @item @tab - a$ @tab uminus (a) @tab Unary subtraction operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	523 @item @tab a .* b$ @tab times (a, b) @tab Element-wise multiplication operator @tab
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	524 @item @tab a * b$ @tab mtimes (a, b) @tab Matrix multiplication operator @tab
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	525 @item @tab a ./ b$ @tab rdivide (a, b) @tab Element-wise right division operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	526 @item @tab a / b$ @tab mrdivide (a, b) @tab Matrix right division operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	527 @item @tab a .\ b$ @tab ldivide (a, b) @tab Element-wise left division operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	528 @item @tab a \ b$ @tab mldivide (a, b) @tab Matrix left division operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	529 @item @tab a .^ b$ @tab ldivide (a, b) @tab Element-wise power operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	530 @item @tab a ^ b$ @tab mldivide (a, b) @tab Matrix power operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	531 @item @tab a < b$ @tab lt (a, b) @tab Less than operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	532 @item @tab a <= b$ @tab le (a, b) @tab Less than or equal to operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	533 @item @tab a > b$ @tab gt (a, b) @tab Greater than operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	534 @item @tab a >= b$ @tab ge (a, b) @tab Greater than or equal to operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	535 @item @tab a == b$ @tab eq (a, b) @tab Equal to operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	536 @item @tab a != b$ @tab ne (a, b) @tab Not equal to operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	537 @item @tab a \& b$ @tab and (a, b) @tab Logical and operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	538 @item @tab a \| b$ @tab or (a, b) @tab Logical or operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	539 @item @tab ! b$ @tab not (a) @tab Logical not operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	540 @item @tab a'$ @tab ctranspose (a) @tab Complex conjugate transpose operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	541 @item @tab a.'$ @tab transpose (a) @tab Transpose operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	542 @item @tab a : b$ @tab colon (a, b) @tab Two element range operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	543 @item @tab a : b : c$ @tab colon (a, b, c) @tab Three element range operator @tab
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	544 @item @tab [a, b]$ @tab horzcat (a, b) @tab Horizontal concatenation operator @tab
17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	545 @item @tab [a; b]$ @tab vertcat (a, b) @tab Vertical concatenation operator @tab
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	546 @item @tab a(s_1, \ldots, s_n)$ @tab subsref (a, s) @tab Subscripted reference @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	547 @item @tab a(s_1, \ldots, s_n) = b$ @tab subsasgn (a, s, b) @tab Subscripted assignment @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	548 @item @tab b (a)$ @tab subsindex (a) @tab Convert to zero-based index @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	549 @item @tab @dfn{display} @tab display (a) @tab Commandline display function @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	550 @end multitable
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	551 @end ifnottex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	552 @caption{Available overloaded operators and their corresponding class method}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	553 @end float
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	554
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	555 An example @code{mtimes} method for our polynomial class might look like
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	556
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	557 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	558 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	559 @EXAMPLEFILE(@polynomial/mtimes.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	560 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	561 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	562
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	563 @node Precedence of Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	564 @subsection Precedence of Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	565
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	566 Many functions and operators take two or more arguments and so the
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	567 case can easily arise that these functions are called with objects of
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	568 different classes. It is therefore necessary to determine the precedence
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	569 of which method of which class to call when there are mixed objects given
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	570 to a function or operator. To do this the @code{superiorto} and
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	571 @code{inferiorto} functions can be used
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	572
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	573 @DOCSTRING(superiorto)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	574
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	575 @DOCSTRING(inferiorto)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	576
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	577 For example with our polynomial class consider the case
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	578
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	579 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	580 2 * polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	581 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	582
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	583 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	584 That mixes an object of the class "double" with an object of the class
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	585 "polynomial". In this case we like to ensure that the return type of
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	586 the above is of the type "polynomial" and so we use the
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	587 @code{superiorto} function in the class constructor. In particular our
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	588 polynomial class constructor would be modified to be
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	589
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	590 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	591 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	592 @EXAMPLEFILE(@polynomial/polynomial_superiorto.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	593 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	594 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	595
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	596 Note that user classes always have higher precedence than built-in
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	597 Octave types. So in fact marking our polynomial class higher than the
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	598 "double" class is in fact not necessary.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	599
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	600
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	601 @node Inheritance and Aggregation
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	602 @section Inheritance and Aggregation
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	603
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	604 Using classes to build new classes is supported by octave through the
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	605 use of both inheritance and aggregation.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	606
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	607 Class inheritance is provided by octave using the @code{class}
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	608 function in the class constructor. As in the case of the polynomial
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	609 class, the octave programmer will create a struct that contains the
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	610 data fields required by the class, and then call the class function to
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	611 indicate that an object is to be created from the struct. Creating a
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	612 child of an existing object is done by creating an object of the
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	613 parent class and providing that object as the third argument of the
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	614 class function.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	615
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	616 This is easily demonstrated by example. Suppose the programmer needs
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	617 an FIR filter, i.e., a filter with a numerator polynomial but a unity
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	618 denominator polynomial. In traditional octave programming, this would
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	619 be performed as follows.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	620
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	621 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	622 @group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	623 octave:1> x = [some data vector];
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	624 octave:2> n = [some coefficient vector];
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	625 octave:3> y = filter (n, 1, x);
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	626 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	627 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	628
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	629 The equivalent class could be implemented in a class directory
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	630 @@FIRfilter that is on the octave path. The constructor is a file
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	631 FIRfilter.m in the class directory.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	632
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	633 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	634 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	635 @EXAMPLEFILE(@FIRfilter/FIRfilter.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	636 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	637 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	638
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	639 As before, the leading comments provide command-line documentation for
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	640 the class constructor. This constructor is very similar to the
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	641 polynomial class constructor, except that we pass a polynomial object
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	642 as the third argument to the class function, telling octave that the
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	643 FIRfilter class will be derived from the polynomial class. Our FIR
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	644 filter does not have any data fields, but we must provide a struct to
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	645 the @code{class} function. The @code{class} function will add an
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	646 element named polynomial to the object struct, so we simply add a
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	647 dummy element named polynomial as the first line of the constructor.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	648 This dummy element will be overwritten by the class function.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	649
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	650 Note further that all our examples provide for the case in which no
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	651 arguments are supplied. This is important since octave will call the
9752 51c21837686f Period spellcheck of Octave documentation to check and fix newly added DOCSTRINGS Rik <rdrider0-list@yahoo.com> parents: 9602 diff changeset	652 constructor with no arguments when loading objects from save files to
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	653 determine the inheritance structure.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	654
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	655 A class may be a child of more than one class (see the documentation
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	656 for the @code{class} function), and inheritance may be nested. There
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	657 is no limitation to the number of parents or the level of nesting
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	658 other than memory or other physical issues.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	659
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	660 As before, we need a @code{display} method. A simple example might be
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	661
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	662 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	663 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	664 @EXAMPLEFILE(@FIRfilter/display.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	665 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	666 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	667
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	668 Note that we have used the polynomial field of the struct to display
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	669 the filter coefficients.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	670
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	671 Once we have the class constructor and display method, we may create
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	672 an object by calling the class constructor. We may also check the
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	673 class type and examine the underlying structure.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	674
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	675 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	676 @group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	677 octave:1> f=FIRfilter(polynomial([1 1 1]/3))
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	678 f.polynomial = 0.333333 + 0.333333 * X + 0.333333 * X ^ 2
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	679 octave:2> class(f)
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	680 ans = FIRfilter
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	681 octave:3> isa(f,"FIRfilter")
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	682 ans = 1
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	683 octave:4> isa(f,"polynomial")
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	684 ans = 1
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	685 octave:5> struct(f)
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	686 ans =
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	687 @{
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	688 polynomial = 0.333333 + 0.333333 * X + 0.333333 * X ^ 2
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	689 @}
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	690 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	691 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	692
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	693 We only need to define a method to actually process data with our
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	694 filter and our class is usable. It is also useful to provide a means
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	695 of changing the data stored in the class. Since the fields in the
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	696 underlying struct are private by default, we could provide a mechanism
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	697 to access the fields. The @code{subsref} method may be used for both.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	698
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	699 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	700 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	701 @EXAMPLEFILE(@FIRfilter/subsref.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	702 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	703 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	704
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	705 The "()" case allows us to filter data using the polynomial provided
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	706 to the constructor.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	707
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	708 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	709 @group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	710 octave:2> f=FIRfilter(polynomial([1 1 1]/3));
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	711 octave:3> x=ones(5,1);
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	712 octave:4> y=f(x)
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	713 y =
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	714
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	715 0.33333
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	716 0.66667
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	717 1.00000
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	718 1.00000
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	719 1.00000
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	720 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	721 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	722
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	723 The "." case allows us to view the contents of the polynomial field.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	724
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	725 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	726 @group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	727 octave:1> f=FIRfilter(polynomial([1 1 1]/3));
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	728 octave:2> f.polynomial
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	729 ans = 0.333333 + 0.333333 * X + 0.333333 * X ^ 2
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	730 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	731 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	732
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	733 In order to change the contents of the object, we need to define a
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	734 @code{subsasgn} method. For example, we may make the polynomial field
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	735 publicly writeable.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	736
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	737 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	738 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	739 @EXAMPLEFILE(@FIRfilter/subsasgn.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	740 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	741 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	742
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	743 So that
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	744
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	745 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	746 @group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	747 octave:6> f=FIRfilter();
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	748 octave:7> f.polynomial = polynomial([1 2 3]);
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	749 f.polynomial = 1 + 2 * X + 3 * X ^ 2
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	750 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	751 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	752
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	753
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	754 Defining the FIRfilter class as a child of the polynomial class
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	755 implies that and FIRfilter object may be used any place that a
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	756 polynomial may be used. This is not a normal use of a filter, so that
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	757 aggregation may be a more sensible design approach. In this case, the
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	758 polynomial is simply a field in the class structure. A class
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	759 constructor for this case might be
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	760
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	761 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	762 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	763 @EXAMPLEFILE(@FIRfilter/FIRfilter_aggregation.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	764 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	765 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	766
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	767 For our example, the remaining class methods remain unchanged.

Mercurial > octave-nkf

annotate doc/interpreter/oop.txi @ 9906:8d20fb66a0dc