octave: doc/interpreter/oop.txi annotate

annotate doc/interpreter/oop.txi @ 17744:d63878346099

maint: Update copyright notices for release.

author	John W. Eaton <jwe@octave.org>
date	Wed, 23 Oct 2013 22:09:27 -0400
parents	4d7f95eb8bfe
children	446c46af4b42

rev	line source
17744 d63878346099 maint: Update copyright notices for release. John W. Eaton <jwe@octave.org> parents: 17289 diff changeset	1 @c Copyright (C) 2008-2013 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
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	57 @tex
050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	58 $$
050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	59 a_0 + a_1 x + a_2 x^2 + \ldots a_n x^n
050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	60 $$
050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	61 @end tex
050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	62 @ifnottex
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	63
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	64 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	65 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	66 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	67
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	68 @end ifnottex
8223 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 @EXAMPLEFILE(@polynomial/polynomial.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	98 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	99
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	100 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	101 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	102 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	103 the call to this constructor function is then
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	104
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	105 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	106 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	107 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	108
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	109 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	110 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	111 for the polynomial constructor @code{help polynomial} will return the
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	112 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	113 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	114 @@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	115 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	116
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	117 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	118 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	119 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	120 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	121 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	122 class.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	123
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	124 To check where a variable is a user class, the @code{isobject} and
11377 473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	125 @code{isa} functions can be used. For example:
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	126
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	127 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	128 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	129 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	130 isobject (p)
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	131 @result{} 1
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	132 isa (p, "polynomial")
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	133 @result{} 1
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	134 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	135 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	136
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	137 @DOCSTRING(isobject)
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 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	140 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	141 @code{methods} function.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	142
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	143 @DOCSTRING(methods)
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 @noindent
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	146 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	147 @code{ismethod} function can be used.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	148
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	149 @DOCSTRING(ismethod)
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 @noindent
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	152 For example:
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	153
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	154 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	155 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	156 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	157 ismethod (p, "roots")
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	158 @result{} 1
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	159 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	160 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	161
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	162 @node Manipulating Classes
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	163 @section Manipulating Classes
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	164
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	165 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	166 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	167 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	168 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	169 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	170 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	171
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	172 @DOCSTRING(display)
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 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	175 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	176
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	177 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	178 @EXAMPLEFILE(@polynomial/display.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	179 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	180
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	181 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	182 Note that in the display method, it makes sense to start the method
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	183 with the line @code{fprintf ("%s =", inputname (1))} to be consistent
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	184 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	185 when displaying the class.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	186
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	187 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	188 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	189 @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	190 argument of the appropriate class it should return a structure with
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	191 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	192
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	193 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	194 @EXAMPLEFILE(@polynomial/get.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	195 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	196
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	197 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	198 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	199 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	200
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	201 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	202 @EXAMPLEFILE(@polynomial/set.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	203 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	204
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	205 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	206 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	207 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	208 must be called like
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	209
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	210 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	211 p = set (p, "a", [1, 0, 0, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	212 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	213
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	214 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	215 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	216 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	217 is discussed in the next section.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	218
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	219 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	220 structure, and so they can be saved to a file in the same manner as a
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	221 structure. For example:
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	222
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	223 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	224 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	225 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	226 save userclass.mat p
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	227 clear p
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	228 load userclass.mat
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	229 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	230 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	231
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	232 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	233 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	234 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	235 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	236 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	237 @code{saveobj} method of the class
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	238
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	239 @DOCSTRING(saveobj)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	240
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	241 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	242 @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	243 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	244 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	245 fields are reinserted into the user object.
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(loadobj)
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 @node Indexing Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	250 @section Indexing Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	251
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	252 @menu
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	253 * Defining Indexing And Indexed Assignment::
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	254 * Indexed Assignment Optimization::
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	255 @end menu
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	256
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	257 @node Defining Indexing And Indexed Assignment
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	258 @subsection Defining Indexing And Indexed Assignment
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	259
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	260 Objects can be indexed with parentheses, either like
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	261 @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	262 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	263 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	264 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	265 @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	266 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	267 determined by the @code{subsref} method.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	268
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	269 @DOCSTRING(subsref)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	270
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 15997 diff changeset	271 For example we might decide that indexing with @qcode{"()"} evaluates the
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 15997 diff changeset	272 polynomial and indexing with @qcode{"@{@}"} returns the @var{n}-th coefficient
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 15997 diff changeset	273 (of @var{n}-th power). In this case the @code{subsref} method of our
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 15997 diff changeset	274 polynomial class might look like
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	275
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	276 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	277 @EXAMPLEFILE(@polynomial/subsref.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	278 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	279
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	280 The equivalent functionality for subscripted assignments uses the
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	281 @code{subsasgn} method.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	282
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	283 @DOCSTRING(subsasgn)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	284
12534 5b9b2645db26 Add optimize_subsasgn_calls function to documentation. Rik <octave@nomad.inbox5.com> parents: 12448 diff changeset	285 @DOCSTRING(optimize_subsasgn_calls)
5b9b2645db26 Add optimize_subsasgn_calls function to documentation. Rik <octave@nomad.inbox5.com> parents: 12448 diff changeset	286
9285 226f6d001ee2 further improve the polynomial example, fix indexing Jaroslav Hajek <highegg@gmail.com> parents: 9251 diff changeset	287 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	288 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	289 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	290 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	291
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	292 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	293 of an object, then the user needs to define the @code{end} method for
12448 f2c080bbd8a5 Fix documentation bugs uncovered while rewriting munge-texi. Rik <octave@nomad.inbox5.com> parents: 11573 diff changeset	294 the class. For example, the @code{end} method for our polynomial class might
f2c080bbd8a5 Fix documentation bugs uncovered while rewriting munge-texi. Rik <octave@nomad.inbox5.com> parents: 11573 diff changeset	295 look like
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	296
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	297 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	298 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	299 @EXAMPLEFILE(@polynomial/end.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	300 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	301 @end example
8223 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 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	304 which is a fairly generic @code{end} method that has a behavior similar to
12448 f2c080bbd8a5 Fix documentation bugs uncovered while rewriting munge-texi. Rik <octave@nomad.inbox5.com> parents: 11573 diff changeset	305 the @code{end} keyword for Octave Array classes. It can then be used as
f2c080bbd8a5 Fix documentation bugs uncovered while rewriting munge-texi. Rik <octave@nomad.inbox5.com> parents: 11573 diff changeset	306 follows:
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	307
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	308 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	309 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	310 p = polynomial ([1,2,3,4]);
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	311 p(end-1)
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	312 @result{} 3
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	313 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	314 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	315
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	316 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	317 and this is controlled with the @code{subsindex} function.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	318
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	319 @DOCSTRING(subsindex)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	320
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	321 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	322 method
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	323
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	324 @DOCSTRING(colon)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	325
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	326 @node Indexed Assignment Optimization
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	327 @subsection Indexed Assignment Optimization
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	328
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	329 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	330 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	331 a call to subsasgn:
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	332
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	333 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	334 @group
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	335 ss = substruct ("()",@{1@});
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	336 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	337 @end group
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	338 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	339
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	340 @noindent
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	341 and the corresponding method looking like this:
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 function x = subsasgn (x, ss, val)
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	346 @dots{}
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	347 x.myfield (ss.subs@{1@}) = val;
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	348 endfunction
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	349 @end group
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	350 @end example
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 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	353 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	354 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	355 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	356 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	357 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	358 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	359 @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	360 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	361 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	362 arrays.
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	363
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	364 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	365 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	366 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	367 call as shown above), i.e.
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	368
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	369 @example
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	370 x(1) = 1;
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	371 @end example
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 @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	374 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	375 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	376 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	377 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	378 element takes constant time.
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	379
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	380 It is important to understand the implications that this optimization brings.
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	381 Since no extra copy of @code{x} in the caller's scope will exist, it is
a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	382 @emph{solely} the callee's responsibility to not leave @code{x} in an invalid
a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	383 state if an error occurs throughout the execution. Also, if the method
a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	384 partially changes @code{x} and then errors out, the changes @emph{will} affect
a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	385 @code{x} in the caller's scope. Deleting or completely replacing @code{x}
a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	386 inside subsasgn will not do anything, however, only indexed assignments matter.
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	387
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	388 Since this optimization may change the way code works (especially if badly
a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	389 written), a built-in variable @code{optimize_subsasgn_calls} is provided to
a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	390 control it. It is on by default. Another option to avoid the effect is to
a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	391 declare subsasgn methods with different output and input arguments, like this:
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	392
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	393 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	394 @group
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	395 function y = subsasgn (x, ss, val)
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	396 @dots{}
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	397 endfunction
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	398 @end group
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	399 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	400
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	401 @node Overloading Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	402 @section Overloading Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	403
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	404 @menu
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	405 * Function Overloading::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	406 * Operator Overloading::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	407 * Precedence of Objects::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	408 @end menu
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	409
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	410 @node Function Overloading
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	411 @subsection Function Overloading
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	412
11573 6f8ffe2c6f76 Grammarcheck txi files for 3.4 release. Rik <octave@nomad.inbox5.com> parents: 11523 diff changeset	413 Any Octave function can be overloaded, and allows an object specific
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	414 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	415 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	416 like
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	417
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	418 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	419 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	420 @EXAMPLEFILE(@polynomial/polyval.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	421 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	422 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	423
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	424 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	425 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	426 polynomial class is the @code{plot} function.
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/plot.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 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	435 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	436 of the roots of the polynomial.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	437
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	438 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	439 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	440 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	441 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	442 @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	443
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	444 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	445 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	446 @EXAMPLEFILE(@polynomial/double.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	447 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	448 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	449
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	450 @node Operator Overloading
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	451 @subsection Operator Overloading
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	452 @cindex addition
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	453 @cindex and operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	454 @cindex arithmetic operators
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	455 @cindex boolean expressions
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	456 @cindex boolean operators
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	457 @cindex comparison expressions
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	458 @cindex complex-conjugate transpose
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	459 @cindex division
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	460 @cindex equality operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	461 @cindex equality, tests for
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	462 @cindex exponentiation
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	463 @cindex expressions, boolean
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	464 @cindex expressions, comparison
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	465 @cindex expressions, logical
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	466 @cindex greater than operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	467 @cindex Hermitian operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	468 @cindex less than operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	469 @cindex logical expressions
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	470 @cindex logical operators
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	471 @cindex matrix multiplication
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	472 @cindex multiplication
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	473 @cindex negation
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	474 @cindex not operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	475 @cindex operators, arithmetic
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	476 @cindex operators, boolean
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	477 @cindex operators, logical
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	478 @cindex operators, relational
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	479 @cindex or operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	480 @cindex quotient
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	481 @cindex relational operators
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	482 @cindex subtraction
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	483 @cindex tests for equality
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	484 @cindex transpose
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	485 @cindex transpose, complex-conjugate
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	486 @cindex unary minus
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	487
15568 38e64d9f0fda doc: Workaround text overlap in pdf documentation caused by bug in Texinfo. Rik <rik@octave.org> parents: 14856 diff changeset	488 @c Need at least one plaintext sentence here between the @node and @float
38e64d9f0fda doc: Workaround text overlap in pdf documentation caused by bug in Texinfo. Rik <rik@octave.org> parents: 14856 diff changeset	489 @c table below or the two will overlap due to a bug in Texinfo.
38e64d9f0fda doc: Workaround text overlap in pdf documentation caused by bug in Texinfo. Rik <rik@octave.org> parents: 14856 diff changeset	490 @c This is not our fault; this is a ridiculous kluge.
38e64d9f0fda doc: Workaround text overlap in pdf documentation caused by bug in Texinfo. Rik <rik@octave.org> parents: 14856 diff changeset	491 The following table shows, for each built-in numerical operation, the
38e64d9f0fda doc: Workaround text overlap in pdf documentation caused by bug in Texinfo. Rik <rik@octave.org> parents: 14856 diff changeset	492 corresponding function name to use when providing an overloaded method for a
38e64d9f0fda doc: Workaround text overlap in pdf documentation caused by bug in Texinfo. Rik <rik@octave.org> parents: 14856 diff changeset	493 user class.
38e64d9f0fda doc: Workaround text overlap in pdf documentation caused by bug in Texinfo. Rik <rik@octave.org> parents: 14856 diff changeset	494
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	495 @float Table,tab:overload_ops
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	496 @opindex +
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	497 @opindex -
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	498 @opindex .*
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	499 @opindex *
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	500 @opindex ./
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	501 @opindex /
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	502 @opindex .\
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	503 @opindex \
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	504 @opindex .^
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	505 @opindex ^
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	506 @opindex <
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	507 @opindex <=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	508 @opindex >
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	509 @opindex >=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	510 @opindex ==
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	511 @opindex !=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	512 @opindex ~=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	513 @opindex &
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	514 @opindex \|
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	515 @opindex !
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	516 @opindex '
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	517 @opindex .'
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	518 @opindex :
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	519 @opindex <
8286 6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	520
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	521 @tex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	522 \vskip 6pt
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	523 {\hbox to \hsize {\hfill\vbox{\offinterlineskip \tabskip=0pt
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	524 \halign{
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	525 \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	526 # \hfil & \vrule # & # \hfil & \vrule # & # \hfil & # \vrule
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	527 width 0.6pt \tabskip=0pt\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	528 \noalign{\hrule height 0.6pt}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	529 & Operation && Method && Description &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	530 \noalign{\hrule}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	531 & $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	532 & $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	533 & $+ a$ && uplus (a) && Unary addition operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	534 & $- a$ && uminus (a) && Unary subtraction operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	535 & $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	536 & $a * b$ && mtimes (a, b) && Matrix multiplication operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	537 & $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	538 & $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	539 & $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	540 & $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	541 & $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	542 & $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	543 & $a < b$ && lt (a, b) && Less than operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	544 & $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	545 & $a > b$ && gt (a, b) && Greater than operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	546 & $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	547 & $a == b$ && eq (a, b) && Equal to operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	548 & $a != b$ && ne (a, b) && Not equal to operator&\cr
14808 f06a16021024 doc: trivial doc fix John W. Eaton <jwe@octave.org> parents: 14805 diff changeset	549 & $a \& b$ && and (a, b) && Logical and operator&\cr
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	550 & $a \| b$ && or (a, b) && Logical or operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	551 & $! b$ && not (a) && Logical not operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	552 & $a'$ && ctranspose (a) && Complex conjugate transpose operator &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	553 & $a.'$ && transpose (a) && Transpose operator &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	554 & $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	555 & $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	556 & $[a, b]$ && horzcat (a, b) && Horizontal concatenation operator &\cr
17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	557 & $[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	558 & $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	559 & $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	560 & $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	561 & {\it display} && display (a) && Commandline display function &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	562 \noalign{\hrule height 0.6pt}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	563 }}\hfill}}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	564 @end tex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	565 @ifnottex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	566 @multitable @columnfractions .1 .20 .20 .40 .1
11447 76f15f3da207 Use @headitem macro to create column heads for @multitable entries. Rik <octave@nomad.inbox5.com> parents: 11403 diff changeset	567 @headitem @tab Operation @tab Method @tab Description @tab
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	568 @item @tab a + b @tab plus (a, b) @tab Binary addition @tab
11377 473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	569 @item @tab a - b @tab minus (a, b) @tab Binary subtraction operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	570 @item @tab + a @tab uplus (a) @tab Unary addition operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	571 @item @tab - a @tab uminus (a) @tab Unary subtraction operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	572 @item @tab a .* b @tab times (a, b) @tab Element-wise multiplication operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	573 @item @tab a * b @tab mtimes (a, b) @tab Matrix multiplication operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	574 @item @tab a ./ b @tab rdivide (a, b) @tab Element-wise right division operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	575 @item @tab a / b @tab mrdivide (a, b) @tab Matrix right division operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	576 @item @tab a .\ b @tab ldivide (a, b) @tab Element-wise left division operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	577 @item @tab a \ b @tab mldivide (a, b) @tab Matrix left division operator @tab
12951 818299a39ae1 oop.txi: Fix incorrect names for power and mpower operators Jordi Gutiérrez Hermoso <jordigh@gmail.com> parents: 12534 diff changeset	578 @item @tab a .^ b @tab power (a, b) @tab Element-wise power operator @tab
818299a39ae1 oop.txi: Fix incorrect names for power and mpower operators Jordi Gutiérrez Hermoso <jordigh@gmail.com> parents: 12534 diff changeset	579 @item @tab a ^ b @tab mpower (a, b) @tab Matrix power operator @tab
11377 473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	580 @item @tab a < b @tab lt (a, b) @tab Less than operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	581 @item @tab a <= b @tab le (a, b) @tab Less than or equal to operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	582 @item @tab a > b @tab gt (a, b) @tab Greater than operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	583 @item @tab a >= b @tab ge (a, b) @tab Greater than or equal to operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	584 @item @tab a == b @tab eq (a, b) @tab Equal to operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	585 @item @tab a != b @tab ne (a, b) @tab Not equal to operator @tab
14808 f06a16021024 doc: trivial doc fix John W. Eaton <jwe@octave.org> parents: 14805 diff changeset	586 @item @tab a & b @tab and (a, b) @tab Logical and operator @tab
11377 473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	587 @item @tab a \| b @tab or (a, b) @tab Logical or operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	588 @item @tab ! b @tab not (a) @tab Logical not operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	589 @item @tab a' @tab ctranspose (a) @tab Complex conjugate transpose operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	590 @item @tab a.' @tab transpose (a) @tab Transpose operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	591 @item @tab a : b @tab colon (a, b) @tab Two element range operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	592 @item @tab a : b : c @tab colon (a, b, c) @tab Three element range operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	593 @item @tab [a, b] @tab horzcat (a, b) @tab Horizontal concatenation operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	594 @item @tab [a; b] @tab vertcat (a, b) @tab Vertical concatenation operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	595 @item @tab a(s_1, @dots{}, s_n) @tab subsref (a, s) @tab Subscripted reference @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	596 @item @tab a(s_1, @dots{}, s_n) = b @tab subsasgn (a, s, b) @tab Subscripted assignment @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment. Rik <octave@nomad.inbox5.com> parents: 10846 diff changeset	597 @item @tab b (a) @tab subsindex (a) @tab Convert to zero-based index @tab
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	598 @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	599 @end multitable
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	600 @end ifnottex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	601 @caption{Available overloaded operators and their corresponding class method}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	602 @end float
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	603
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	604 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	605
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	606 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	607 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	608 @EXAMPLEFILE(@polynomial/mtimes.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	609 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	610 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	611
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	612 @node Precedence of Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	613 @subsection Precedence of Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	614
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	615 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	616 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	617 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	618 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	619 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	620 @code{inferiorto} functions can be used
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	621
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	622 @DOCSTRING(superiorto)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	623
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	624 @DOCSTRING(inferiorto)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	625
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	626 For example with our polynomial class consider the case
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	627
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	628 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	629 2 * polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	630 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	631
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	632 @noindent
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 15997 diff changeset	633 That mixes an object of the class @qcode{"double"} with an object of the class
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 15997 diff changeset	634 @qcode{"polynomial"}. In this case we like to ensure that the return type of
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 15997 diff changeset	635 the above is of the type @qcode{"polynomial"} and so we use the
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	636 @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	637 polynomial class constructor would be modified to be
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	638
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	639 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	640 @EXAMPLEFILE(@polynomial/polynomial_superiorto.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	641 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	642
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	643 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	644 Octave types. So in fact marking our polynomial class higher than the
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 15997 diff changeset	645 @qcode{"double"} class is in fact not necessary.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	646
15997 d53fa7e43aa9 doc: what happens when two objects have same precedence Carnë Draug <carandraug@octave.org> parents: 15568 diff changeset	647 When faced with two objects that have the same precedence, Octave will use the
d53fa7e43aa9 doc: what happens when two objects have same precedence Carnë Draug <carandraug@octave.org> parents: 15568 diff changeset	648 method of the object that appears first on the list of arguments.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	649
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	650 @node Inheritance and Aggregation
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	651 @section Inheritance and Aggregation
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	652
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	653 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	654 use of both inheritance and aggregation.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	655
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	656 Class inheritance is provided by octave using the @code{class}
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	657 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	658 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	659 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	660 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	661 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	662 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	663 class function.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	664
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	665 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	666 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	667 denominator polynomial. In traditional octave programming, this would
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	668 be performed as follows.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	669
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	670 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	671 @group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	672 octave:1> x = [some data vector];
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	673 octave:2> n = [some coefficient vector];
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	674 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	675 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	676 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	677
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	678 The equivalent class could be implemented in a class directory
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	679 @@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	680 FIRfilter.m in the class directory.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	681
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	682 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	683 @EXAMPLEFILE(@FIRfilter/FIRfilter.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	684 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	685
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	686 As before, the leading comments provide command-line documentation for
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	687 the class constructor. This constructor is very similar to the
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	688 polynomial class constructor, except that we pass a polynomial object
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	689 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	690 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	691 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	692 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	693 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	694 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	695 This dummy element will be overwritten by the class function.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	696
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	697 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	698 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	699 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	700 determine the inheritance structure.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	701
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	702 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	703 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	704 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	705 other than memory or other physical issues.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	706
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	707 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	708
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	709 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	710 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	711 @EXAMPLEFILE(@FIRfilter/display.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	712 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	713 @end example
9251 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 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	716 the filter coefficients.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	717
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	718 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	719 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	720 class type and examine the underlying structure.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	721
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	722 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	723 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	724 octave:1> f = FIRfilter (polynomial ([1 1 1]/3))
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	725 f.polynomial = 0.333333 + 0.333333 * X + 0.333333 * X ^ 2
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	726 octave:2> class (f)
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	727 ans = FIRfilter
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	728 octave:3> isa (f,"FIRfilter")
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	729 ans = 1
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	730 octave:4> isa (f,"polynomial")
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	731 ans = 1
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	732 octave:5> struct (f)
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	733 ans =
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	734 @{
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	735 polynomial = 0.333333 + 0.333333 * X + 0.333333 * X ^ 2
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	736 @}
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	737 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	738 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	739
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	740 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	741 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	742 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	743 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	744 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	745
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	746 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	747 @EXAMPLEFILE(@FIRfilter/subsref.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	748 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	749
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 15997 diff changeset	750 The @qcode{"()"} case allows us to filter data using the polynomial provided
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	751 to the constructor.
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 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	754 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	755 octave:2> f = FIRfilter (polynomial ([1 1 1]/3));
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	756 octave:3> x = ones (5,1);
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	757 octave:4> y = f(x)
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	758 y =
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	759
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	760 0.33333
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	761 0.66667
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	762 1.00000
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	763 1.00000
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	764 1.00000
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	765 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	766 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	767
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 15997 diff changeset	768 The @qcode{"."} case allows us to view the contents of the polynomial field.
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	769
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	770 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	771 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	772 octave:1> f = FIRfilter (polynomial ([1 1 1]/3));
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	773 octave:2> f.polynomial
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	774 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	775 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	776 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	777
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	778 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	779 @code{subsasgn} method. For example, we may make the polynomial field
10791 3140cb7a05a1 Add spellchecker scripts for Octave and run spellcheck of documentation Rik <octave@nomad.inbox5.com> parents: 9906 diff changeset	780 publicly writable.
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	781
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	782 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	783 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	784 @EXAMPLEFILE(@FIRfilter/subsasgn.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	785 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	786 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	787
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	788 So that
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	789
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	790 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	791 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	792 octave:6> f = FIRfilter ();
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	793 octave:7> f.polynomial = polynomial ([1 2 3]);
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	794 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	795 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	796 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	797
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	798 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	799 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	800 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	801 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	802 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	803 constructor for this case might be
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	804
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	805 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	806 @EXAMPLEFILE(@FIRfilter/FIRfilter_aggregation.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	807 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	808
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	809 For our example, the remaining class methods remain unchanged.

Mercurial > octave

annotate doc/interpreter/oop.txi @ 17744:d63878346099