Mercurial > octave-nkf

annotate doc/interpreter/oop.txi @ 9758:09da0bd91412

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Periodic grammar check of Octave documentation files to ensure common format Use double spaces after a period at start of new sentence Do not use @iftex blocks where @tex block is sufficient
author Rik <rdrider0-list@yahoo.com>
date Fri, 23 Oct 2009 09:28:14 -0700
parents 51c21837686f
children 8d20fb66a0dc
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
9245
16f53d29049f update copyright notices
John W. Eaton <jwe@octave.org>
parents: 9209
diff changeset
1 @c Copyright (C) 2008, 2009 David Bateman
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
2 @c Copyright (C) 2009 VZLU Prague
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
3 @c
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
4 @c This file is part of Octave.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
5 @c
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
6 @c Octave is free software; you can redistribute it and/or modify it
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
7 @c under the terms of the GNU General Public License as published by the
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
8 @c Free Software Foundation; either version 3 of the License, or (at
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
9 @c your option) any later version.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
10 @c
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
11 @c Octave is distributed in the hope that it will be useful, but WITHOUT
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
12 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
13 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
14 @c for more details.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
15 @c
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
16 @c You should have received a copy of the GNU General Public License
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
17 @c along with Octave; see the file COPYING. If not, see
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
18 @c <http://www.gnu.org/licenses/>.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
19
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
20 @c FIXME
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
21 @c For now can't include "@" character in the path name, and so name
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
22 @c the example directory without the "@"!!
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
23
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
24 @macro classfile{class, file}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
25 @example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
26 @group
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
27 @verbatiminclude @value{abs_top_srcdir}/examples/\class\/\file\
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
28 @end group
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
29 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
30 @end macro
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
31
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
32 @macro polynomialfile{file}
8256
dba0037e6602 Import new texinfo.tex allowing @ in directory name. Update OOP example class location
David Bateman <dbateman@free.fr>
parents: 8235
diff changeset
33 @classfile{@@polynomial,\file\}
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
34 @end macro
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
35
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
36 @node Object Oriented Programming
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
37 @chapter Object Oriented Programming
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
38
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
39 Octave includes the capability to include user classes, including the
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
40 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
41 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
42 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
43 issue of class precedence in mixed class operations.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
44
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
45 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
46 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
47 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
48 functions.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
49
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
50 @menu
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
51 * Creating a Class::
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
52 * Manipulating Classes::
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
53 * Indexing Objects::
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
54 * Overloading Objects::
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
55 * Inheritance and Aggregation::
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
56 @end menu
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
57
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
58 @node Creating a Class
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
59 @section Creating a Class
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
60
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
61 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
62 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
63 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
64 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
65 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
66 fully grasp the techniques described.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
67
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
68 The polynomial class is used to represent polynomials of the form
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
69
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
70 @example
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
71 @group
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
72 @tex
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
73 $a_0 + a_1 x + a_2 x^2 + \ldots a_n x^n$
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
74 @end tex
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
75 @ifnottex
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
76 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
77 @end ifnottex
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
78 @end group
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
79 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
80
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
81 @noindent
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
82 where
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
83 @tex
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
84 $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
85 @end tex
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
86 @ifnottex
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
87 a0, a1, etc. are real scalars.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
88 @end ifnottex
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
89 Thus the polynomial can be represented by a vector
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
90
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
91 @example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
92 a = [a0, a1, a2, @dots{}, an];
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
93 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
94
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
95 We therefore now have sufficient information about the requirements of
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
96 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
97 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
98 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
99 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
100 the @@polynomial directory.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
101
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
102 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
103 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
104 @file{@@polynomial/polynomial.m}. Also ideally when the constructor is
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
105 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
106 our polynomial might look like
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
107
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
108 @polynomialfile{polynomial.m}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
109
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
110 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
111 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
112 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
113 the call to this constructor function is then
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
114
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
115 @example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
116 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
117 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
118
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
119 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
120 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
121 for the polynomial constructor @code{help polynomial} will return the
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
122 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
123 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
124 @@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
125 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
126
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
127 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
128 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
129 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
130 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
131 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
132 class.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
133
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
134 To check where a variable is a user class, the @code{isobject} and
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
135 @code{isa} functions can be used. for 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 @example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
138 @group
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
139 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
140 isobject (p)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
141 @result{} 1
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
142 isa (p, "polynomial")
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
143 @result{} 1
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
144 @end group
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
145 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
146
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
147 @DOCSTRING(isobject)
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 @noindent
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
150 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
151 @code{methods} function.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
152
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
153 @DOCSTRING(methods)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
154
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
155 @noindent
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
156 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
157 @code{ismethod} function can be used.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
158
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
159 @DOCSTRING(ismethod)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
160
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
161 @noindent
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
162 For example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
163
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
164 @example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
165 @group
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
166 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
167 ismethod (p, "roots")
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
168 @result{} 1
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
169 @end group
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
170 @end example
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 @node Manipulating Classes
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
173 @section Manipulating Classes
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
174
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
175 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
176 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
177 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
178 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
179 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
180 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
181
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
182 @DOCSTRING(display)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
183
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
184 @noindent
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
185 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
186
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
187 @polynomialfile{display.m}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
188
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
189 @noindent
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
190 Note that in the display method, it makes sense to start the method
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
191 with the line @code{fprintf("%s =", inputname(1))} to be consistent
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
192 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
193 when displaying the class.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
194
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
195 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
196 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
197 @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
198 argument of the appropriate class it should return a structure with
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
199 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
200
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
201 @polynomialfile{get.m}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
202
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
203 @noindent
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
204 Similarly, the @code{set} method should taken as its first argument an
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
205 object to modify, and then take property/value pairs to be modified.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
206
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
207 @polynomialfile{set.m}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
208
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
209 @noindent
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
210 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
211 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
212 must be called like
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 @example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
215 p = set (p, "a", [1, 0, 0, 0, 1]);
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
216 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
217
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
218 @noindent
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
219 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
220 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
221 is discussed in the next section.
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 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
224 structure, and so they can be saved to a file in the same manner as a
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
225 structure. For example
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
226
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
227 @example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
228 @group
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
229 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
230 save userclass.mat p
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
231 clear p
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
232 load userclass.mat
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
233 @end group
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
234 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
235
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
236 @noindent
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
237 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
238 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
239 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
240 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
241 @code{saveobj} method of the class
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
242
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
243 @DOCSTRING(saveobj)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
244
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
245 @noindent
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
246 @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
247 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
248 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
249 fields are reinserted into the user object.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
250
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
251 @DOCSTRING(loadobj)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
252
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
253 @node Indexing Objects
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
254 @section Indexing Objects
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
255
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
256 @menu
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
257 * Defining Indexing And Indexed Assignment::
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
258 * Indexed Assignment Optimization::
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
259 @end menu
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
260
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
261 @node Defining Indexing And Indexed Assignment
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
262 @subsection Defining Indexing And Indexed Assignment
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
263
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
264 Objects can be indexed with parentheses, either like
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
265 @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
266 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
267 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
268 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
269 @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
270 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
271 determined by the @code{subsref} method.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
272
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
273 @DOCSTRING(subsref)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
274
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
275 For example we might decide that indexing with "()" evaluates the
9285
226f6d001ee2 further improve the polynomial example, fix indexing
Jaroslav Hajek <highegg@gmail.com>
parents: 9251
diff changeset
276 polynomial and indexing with "@{@}" returns the @var{n}-th coefficient (of @var{n}-th power).
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
277 In this case the @code{subsref} method of our polynomial class might look like
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
278
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
279 @polynomialfile{subsref.m}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
280
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
281 The equivalent functionality for subscripted assignments uses the
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
282 @code{subsasgn} method.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
283
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
284 @DOCSTRING(subsasgn)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
285
9285
226f6d001ee2 further improve the polynomial example, fix indexing
Jaroslav Hajek <highegg@gmail.com>
parents: 9251
diff changeset
286 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
287 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
288 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
289 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
290
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
291 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
292 of an object, then the user needs to define the @code{end} method for
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
293 the class.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
294
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
295 @DOCSTRING(end)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
296
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
297 For example the @code{end} method for our polynomial class might look like
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
298
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
299 @polynomialfile{end.m}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
300
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
301 @noindent
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
302 which is a fairly generic @code{end} method that has a behavior similar to
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
303 the @code{end} keyword for Octave Array classes. It can then be used for
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
304 example like
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
305
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
306 @example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
307 @group
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
308 p = polynomial([1,2,3,4]);
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
309 p(end-1)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
310 @result{} 3
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
311 @end group
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
312 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
313
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
314 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
315 and this is controlled with the @code{subsindex} function.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
316
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
317 @DOCSTRING(subsindex)
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 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
320 method
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
321
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
322 @DOCSTRING(colon)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
323
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
324 @node Indexed Assignment Optimization
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
325 @subsection Indexed Assignment Optimization
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
326
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
327 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
328 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
329 a call to subsasgn:
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
330
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
331 @example
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
332 @group
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
333 ss = substruct ("()",@{1@});
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
334 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
335 @end group
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
336 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
337
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
338 and the corresponding method looking like this:
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
339
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
340 @example
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
341 @group
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
342 function x = subsasgn (x, ss, val)
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
343 @dots{}
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
344 x.myfield(ss.subs@{1@}) = val;
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
345 endfunction
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
346 @end group
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
347 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
348
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
349 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
350 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
351 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
352 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
353 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
354 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
355 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
356 @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
357 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
358 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
359 arrays.
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
360
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
361 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
362 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
363 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
364 call as shown above), i.e.
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
365
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
366 @example
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
367 x(1) = 1;
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
368 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
369
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
370 @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
371 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
372 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
373 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
374 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
375 element takes constant time.
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
376
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
377 It is important to understand the implications that this optimization brings.
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
378 Since no extra copy of @code{x} in the caller's scope will exist, it is @i{solely}
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
379 the callee's responsibility to not leave @code{x} in an invalid state if an error
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
380 occurs throughout the execution. Also, if the method partially changes @code{x}
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
381 and then errors out, the changes @i{will} affect @code{x} in the caller's scope.
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
382 Deleting or completely replacing @code{x} inside subsasgn will not do anything,
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
383 however, only indexed assignments matter.
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
384
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
385 Since this optimization may change the way code works (especially if badly written),
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
386 a built-in variable @code{optimize_subsasgn_calls} is provided to control it.
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
387 It is on by default.
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
388 Another option to avoid the effect is to declare subsasgn methods with different
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
389 output and input arguments, like this:
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
390
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
391 @example
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
392 @group
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
393 function y = subsasgn (x, ss, val)
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
394 @dots{}
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
395 endfunction
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
396 @end group
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
397 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
398
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
399 @node Overloading Objects
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
400 @section Overloading Objects
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
401
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
402 @menu
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
403 * Function Overloading::
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
404 * Operator Overloading::
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
405 * Precedence of Objects::
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
406 @end menu
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
407
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
408 @node Function Overloading
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
409 @subsection Function Overloading
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
410
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
411 Any Octave function can be overloaded, and allows a object specific
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
412 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
413 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
414 like
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
415
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
416 @polynomialfile{polyval.m}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
417
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
418 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
419 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
420 polynomial class is the @code{plot} function.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
421
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
422 @polynomialfile{plot.m}
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 @noindent
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
425 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
426 of the roots of the polynomial.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
427
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
428 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
429 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
430 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
431 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
432 @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
433
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
434 @polynomialfile{double.m}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
435
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
436 @node Operator Overloading
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
437 @subsection Operator Overloading
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
438
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
439 @float Table,tab:overload_ops
8286
6f2d95255911 fix @seealso references to point to existing anchors
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8256
diff changeset
440
6f2d95255911 fix @seealso references to point to existing anchors
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8256
diff changeset
441 @anchor{doc-rdivide} @anchor{doc-plus} @anchor{doc-minus} @anchor{doc-uminus}
6f2d95255911 fix @seealso references to point to existing anchors
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8256
diff changeset
442 @anchor{doc-uplus} @anchor{doc-times} @anchor{doc-mtimes} @anchor{doc-mrdivide}
6f2d95255911 fix @seealso references to point to existing anchors
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8256
diff changeset
443 @anchor{doc-ldivide} @anchor{doc-mldivide} @anchor{doc-power}
6f2d95255911 fix @seealso references to point to existing anchors
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8256
diff changeset
444 @anchor{doc-mpower} @anchor{doc-lt} @anchor{doc-le} @anchor{doc-gt}
6f2d95255911 fix @seealso references to point to existing anchors
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8256
diff changeset
445 @anchor{doc-ge} @anchor{doc-eq} @anchor{doc-ne} @anchor{doc-and}
6f2d95255911 fix @seealso references to point to existing anchors
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8256
diff changeset
446 @anchor{doc-or} @anchor{doc-not} @anchor{doc-ctranspose} @anchor{doc-transpose}
6f2d95255911 fix @seealso references to point to existing anchors
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8256
diff changeset
447
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
448 @tex
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
449 \vskip 6pt
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
450 {\hbox to \hsize {\hfill\vbox{\offinterlineskip \tabskip=0pt
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
451 \halign{
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
452 \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
453 # \hfil & \vrule # & # \hfil & \vrule # & # \hfil & # \vrule
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
454 width 0.6pt \tabskip=0pt\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
455 \noalign{\hrule height 0.6pt}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
456 & Operation && Method && Description &\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
457 \noalign{\hrule}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
458 & $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
459 & $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
460 & $+ a$ && uplus (a) && Unary addition operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
461 & $- a$ && uminus (a) && Unary subtraction operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
462 & $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
463 & $a * b$ && mtimes (a, b) && Matrix multiplication operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
464 & $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
465 & $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
466 & $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
467 & $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
468 & $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
469 & $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
470 & $a < b$ && lt (a, b) && Less than operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
471 & $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
472 & $a > b$ && gt (a, b) && Greater than operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
473 & $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
474 & $a == b$ && eq (a, b) && Equal to operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
475 & $a != b$ && ne (a, b) && Not equal to operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
476 & $a \& b$ && and (a, b) && Logical and operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
477 & $a | b$ && or (a, b) && Logical or operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
478 & $! b$ && not (a) && Logical not operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
479 & $a'$ && ctranspose (a) && Complex conjugate transpose operator &\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
480 & $a.'$ && transpose (a) && Transpose operator &\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
481 & $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
482 & $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
483 & $[a, b]$ && horzcat (a, b) && Horizontal concatenation operator &\cr
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
484 & $[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
485 & $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
486 & $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
487 & $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
488 & {\it display} && display (a) && Commandline display function &\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
489 \noalign{\hrule height 0.6pt}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
490 }}\hfill}}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
491 @end tex
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
492 @ifnottex
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
493 @multitable @columnfractions .1 .20 .20 .40 .1
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
494 @item @tab Operation @tab Method @tab Description @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
495 @item @tab a + b @tab plus (a, b) @tab Binary addition @tab
8295
16819ca24fa5 fix typo in docs
John W. Eaton <jwe@octave.org>
parents: 8286
diff changeset
496 @item @tab a - b$ @tab minus (a, b) @tab Binary subtraction operator @tab
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
497 @item @tab + a$ @tab uplus (a) @tab Unary addition operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
498 @item @tab - a$ @tab uminus (a) @tab Unary subtraction operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
499 @item @tab a .* b$ @tab times (a, b) @tab Element-wise multiplication operator @tab
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
500 @item @tab a * b$ @tab mtimes (a, b) @tab Matrix multiplication operator @tab
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
501 @item @tab a ./ b$ @tab rdivide (a, b) @tab Element-wise right division operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
502 @item @tab a / b$ @tab mrdivide (a, b) @tab Matrix right division operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
503 @item @tab a .\ b$ @tab ldivide (a, b) @tab Element-wise left division operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
504 @item @tab a \ b$ @tab mldivide (a, b) @tab Matrix left division operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
505 @item @tab a .^ b$ @tab ldivide (a, b) @tab Element-wise power operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
506 @item @tab a ^ b$ @tab mldivide (a, b) @tab Matrix power operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
507 @item @tab a < b$ @tab lt (a, b) @tab Less than operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
508 @item @tab a <= b$ @tab le (a, b) @tab Less than or equal to operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
509 @item @tab a > b$ @tab gt (a, b) @tab Greater than operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
510 @item @tab a >= b$ @tab ge (a, b) @tab Greater than or equal to operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
511 @item @tab a == b$ @tab eq (a, b) @tab Equal to operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
512 @item @tab a != b$ @tab ne (a, b) @tab Not equal to operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
513 @item @tab a \& b$ @tab and (a, b) @tab Logical and operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
514 @item @tab a | b$ @tab or (a, b) @tab Logical or operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
515 @item @tab ! b$ @tab not (a) @tab Logical not operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
516 @item @tab a'$ @tab ctranspose (a) @tab Complex conjugate transpose operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
517 @item @tab a.'$ @tab transpose (a) @tab Transpose operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
518 @item @tab a : b$ @tab colon (a, b) @tab Two element range operator @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
519 @item @tab a : b : c$ @tab colon (a, b, c) @tab Three element range operator @tab
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
520 @item @tab [a, b]$ @tab horzcat (a, b) @tab Horizontal concatenation operator @tab
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
521 @item @tab [a; b]$ @tab vertcat (a, b) @tab Vertical concatenation operator @tab
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
522 @item @tab a(s_1, \ldots, s_n)$ @tab subsref (a, s) @tab Subscripted reference @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
523 @item @tab a(s_1, \ldots, s_n) = b$ @tab subsasgn (a, s, b) @tab Subscripted assignment @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
524 @item @tab b (a)$ @tab subsindex (a) @tab Convert to zero-based index @tab
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
525 @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
526 @end multitable
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
527 @end ifnottex
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
528 @caption{Available overloaded operators and their corresponding class method}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
529 @end float
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
530
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
531 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
532
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
533 @polynomialfile{mtimes.m}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
534
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
535 @node Precedence of Objects
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
536 @subsection Precedence of Objects
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
537
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
538 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
539 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
540 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
541 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
542 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
543 @code{inferiorto} functions can be used
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
544
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
545 @DOCSTRING(superiorto)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
546
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
547 @DOCSTRING(inferiorto)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
548
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
549 For example with our polynomial class consider the case
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
550
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
551 @example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
552 2 * polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
553 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
554
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
555 @noindent
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
556 That mixes an object of the class "double" with an object of the class
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
557 "polynomial". In this case we like to ensure that the return type of
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
558 the above is of the type "polynomial" and so we use the
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
559 @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
560 polynomial class constructor would be modified to be
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
561
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
562 @polynomialfile{polynomial_superiorto.m}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
563
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
564 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
565 Octave types. So in fact marking our polynomial class higher than the
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
566 "double" class is in fact not necessary.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
567
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
568
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
569 @node Inheritance and Aggregation
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
570 @section Inheritance and Aggregation
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
571
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
572 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
573 use of both inheritance and aggregation.
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
574
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
575 Class inheritance is provided by octave using the @code{class}
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
576 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
577 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
578 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
579 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
580 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
581 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
582 class function.
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
583
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
584 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
585 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
586 denominator polynomial. In traditional octave programming, this would
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
587 be performed as follows.
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
588
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
589 @example
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
590 @group
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
591 octave:1> x = [some data vector];
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
592 octave:2> n = [some coefficient vector];
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
593 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
594 @end group
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
595 @end example
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
596
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
597 The equivalent class could be implemented in a class directory
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
598 @@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
599 FIRfilter.m in the class directory.
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
600
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
601 @classfile{@@FIRfilter,FIRfilter.m}
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
602
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
603 As before, the leading comments provide command-line documentation for
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
604 the class constructor. This constructor is very similar to the
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
605 polynomial class constructor, except that we pass a polynomial object
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
606 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
607 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
608 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
609 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
610 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
611 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
612 This dummy element will be overwritten by the class function.
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
613
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
614 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
615 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
616 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
617 determine the inheritance structure.
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
618
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
619 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
620 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
621 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
622 other than memory or other physical issues.
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
623
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
624 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
625
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
626 @classfile{@@FIRfilter,display.m}
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
627
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
628 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
629 the filter coefficients.
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
630
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
631 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
632 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
633 class type and examine the underlying structure.
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
634
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
635 @example
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
636 @group
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
637 octave:1> f=FIRfilter(polynomial([1 1 1]/3))
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
638 f.polynomial = 0.333333 + 0.333333 * X + 0.333333 * X ^ 2
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
639 octave:2> class(f)
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
640 ans = FIRfilter
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
641 octave:3> isa(f,"FIRfilter")
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
642 ans = 1
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
643 octave:4> isa(f,"polynomial")
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
644 ans = 1
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
645 octave:5> struct(f)
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
646 ans =
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
647 @{
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
648 polynomial = 0.333333 + 0.333333 * X + 0.333333 * X ^ 2
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
649 @}
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
650 @end group
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
651 @end example
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 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
654 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
655 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
656 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
657 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
658
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
659 @classfile{@@FIRfilter,subsref.m}
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
660
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
661 The "()" case allows us to filter data using the polynomial provided
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
662 to the constructor.
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
663
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
664 @example
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
665 @group
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
666 octave:2> f=FIRfilter(polynomial([1 1 1]/3));
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
667 octave:3> x=ones(5,1);
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
668 octave:4> y=f(x)
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
669 y =
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
670
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
671 0.33333
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
672 0.66667
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
673 1.00000
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
674 1.00000
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
675 1.00000
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
676 @end group
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
677 @end example
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
678
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
679 The "." case allows us to view the contents of the polynomial field.
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
680
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
681 @example
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
682 @group
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
683 octave:1> f=FIRfilter(polynomial([1 1 1]/3));
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
684 octave:2> f.polynomial
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
685 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
686 @end group
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
687 @end example
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
688
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
689 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
690 @code{subsasgn} method. For example, we may make the polynomial field
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
691 publicly writeable.
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
692
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
693 @classfile{@@FIRfilter,subsasgn.m}
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
694
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
695 So that
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 @example
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
698 @group
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
699 octave:6> f=FIRfilter();
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
700 octave:7> f.polynomial = polynomial([1 2 3]);
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
701 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
702 @end group
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
703 @end example
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
704
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
705
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
706 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
707 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
708 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
709 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
710 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
711 constructor for this case might be
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
712
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
713 @classfile{@@FIRfilter,FIRfilter_aggregation.m}
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 For our example, the remaining class methods remain unchanged.