Mercurial > octave

annotate doc/interpreter/oop.txi @ 21076:b433f9990452

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
strip trailing whitespace from files * NEWS, oop.txi, ov.h, dSparse.h, f77-fcn.h, lo-array-gripes.h, display.m, int2str.m, num2str.m, subsindex.m, fileattrib.m, parser.tst: Strip trailing whitespace.
author John W. Eaton <jwe@octave.org>
date Fri, 15 Jan 2016 12:46:58 -0500
parents a9ed4104ecfd
children 7c143e73e921
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
19697
4197fc428c7d maint: Update copyright notices for 2015.
John W. Eaton <jwe@octave.org>
parents: 19593
diff changeset
1 @c Copyright (C) 2008-2015 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.
19593
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 17744
diff changeset
10 @c
8223
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.
19593
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 17744
diff changeset
15 @c
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
16 @c You should have received a copy of the GNU General Public License
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
17 @c along with Octave; see the file COPYING. If not, see
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
18 @c <http://www.gnu.org/licenses/>.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
19
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
20 @c FIXME
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
21 @c For now can't include "@" character in the path name, and so name
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
22 @c the example directory without the "@"!!
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
23
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
24 @node Object Oriented Programming
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
25 @chapter Object Oriented Programming
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
26
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
27 Octave has the ability to create user-defined classes---including the
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
28 capabilities of operator and function overloading. Classes can protect
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
29 internal properties so that they may not be altered accidentally which
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
30 facilitates data encapsulation. In addition, rules can be created to address
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
31 the issue of class precedence in mixed class operations.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
32
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
33 This chapter discusses the means of constructing a user class, how to query and
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
34 set the properties of a class, and how to overload operators and functions.
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
35 Throughout this chapter real code examples are given using a class designed
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
36 for polynomials.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
37
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
38 @menu
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
39 * Creating a Class::
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
40 * Class Methods::
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
41 * Indexing Objects::
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
42 * Overloading Objects::
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
43 * Inheritance and Aggregation::
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
44 @end menu
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
45
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
46 @node Creating a Class
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
47 @section Creating a Class
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
48
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
49 This chapter illustrates user-defined classes and object oriented programming
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
50 through a custom class designed for polynomials. This class was chosen for
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
51 its simplicity which does not distract unnecessarily from the discussion of
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
52 the programming features of Octave. Even so, a bit of background on the goals
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
53 of the polynomial class is necessary before the syntax and techniques of Octave
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
54 object oriented programming are introduced.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
55
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
56 The polynomial class is used to represent polynomials of the form
14093
050bc580cb60 doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 12951
diff changeset
57 @tex
050bc580cb60 doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 12951
diff changeset
58 $$
050bc580cb60 doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 12951
diff changeset
59 a_0 + a_1 x + a_2 x^2 + \ldots a_n x^n
050bc580cb60 doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 12951
diff changeset
60 $$
050bc580cb60 doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 12951
diff changeset
61 @end tex
050bc580cb60 doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 12951
diff changeset
62 @ifnottex
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
63
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
64 @example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
65 a0 + a1 * x + a2 * x^2 + @dots{} + an * x^n
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
66 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
67
14093
050bc580cb60 doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 12951
diff changeset
68 @end ifnottex
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
69 @noindent
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
70 where
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
71 @tex
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
72 $a_0$, $a_1$, etc. are elements of $\Re$.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
73 @end tex
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
74 @ifnottex
9073
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
75 a0, a1, etc. are real scalars.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
76 @end ifnottex
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
77 Thus the polynomial can be represented by a vector
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
78
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
79 @example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
80 a = [a0, a1, a2, @dots{}, an];
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
81 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
82
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
83 This is a sufficient specification to begin writing the constructor for the
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
84 polynomial class. All object oriented classes in Octave must be located in a
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
85 directory that is the name of the class prepended with the @samp{@@} symbol.
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
86 For example, the polynomial class will have all of its methods defined in the
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
87 @file{@@polynomial} directory.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
88
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
89 The constructor for the class must be the name of the class itself; in this
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
90 example the constructor resides in the file @file{@@polynomial/polynomial.m}.
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
91 Ideally, even when the constructor is called with no arguments it should return
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
92 a valid object. A constructor for the polynomial class might look like
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
93
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
94 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
95 @EXAMPLEFILE(@polynomial/polynomial.m)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
96 @end example
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
97
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
98 Note that the return value of the constructor must be the output of the
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
99 @code{class} function. The first argument to the @code{class} function is a
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
100 structure and the second is the name of the class itself. An example of
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
101 calling the class constructor to create an instance is
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
102
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
103 @example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
104 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
105 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
106
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
107 Methods are defined by m-files in the class directory and can have embedded
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
108 documentation the same as any other m-file. The help for the constructor can
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
109 be obtained by using the constructor name alone, that is, for the polynomial
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
110 constructor @code{help polynomial} will return the help string. Help can be
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
111 restricted to a particular class by using the class directory name followed
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
112 by the method. For example, @code{help @@polynomial/polynomial} is another
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
113 way of displaying the help string for the polynomial constructor. This second
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
114 means is the only way to obtain help for the overloaded methods and functions
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
115 of a class.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
116
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
117 The same specification mechanism can be used wherever Octave expects a function
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
118 name. For example @code{type @@polynomial/display} will print the code of the
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
119 display method of the polynomial class to the screen, and
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
120 @code{dbstop @@polynomial/display} will set a breakpoint at the first
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
121 executable line of the display method of the polynomial class.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
122
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
123 To check whether a variable belongs to a user class, the @code{isobject} and
11377
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
124 @code{isa} functions can be used. For example:
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
125
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
126 @example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
127 @group
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
128 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
129 isobject (p)
14093
050bc580cb60 doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 12951
diff changeset
130 @result{} 1
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
131 isa (p, "polynomial")
14093
050bc580cb60 doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 12951
diff changeset
132 @result{} 1
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
133 @end group
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
134 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
135
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
136 @DOCSTRING(isobject)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
137
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
138 @noindent
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
139 The available methods of a class can be displayed with the @code{methods}
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
140 function.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
141
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
142 @DOCSTRING(methods)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
143
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
144 @noindent
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
145 To inquire whether a particular method exists for a user class, the
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
146 @code{ismethod} function can be used.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
147
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
148 @DOCSTRING(ismethod)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
149
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
150 @noindent
10846
a4f482e66b65 Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
151 For example:
8223
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 @example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
154 @group
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
155 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
156 ismethod (p, "roots")
14093
050bc580cb60 doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 12951
diff changeset
157 @result{} 1
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
158 @end group
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
159 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
160
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
161 @node Class Methods
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
162 @section Class Methods
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
163
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
164 There are a number of basic class methods that can (and should) be defined to
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
165 allow the contents of the classes to be queried and set. The most basic of
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
166 these is the @code{display} method. The @code{display} method is used by
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
167 Octave whenever a class should be displayed on the screen. Usually this is the
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
168 result of an Octave expression that doesn't end with a semicolon. If this
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
169 method is not defined, then Octave won't print anything when displaying the
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
170 contents of a class which can be confusing.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
171
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
172 @DOCSTRING(display)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
173
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
174 @noindent
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
175 An example of a display method for the polynomial class might be
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
176
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
177 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
178 @EXAMPLEFILE(@polynomial/display.m)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
179 @end example
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
180
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
181 @noindent
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
182 Note that in the display method it makes sense to start the method with the
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
183 line @w{@code{printf ("%s =", inputname (1))}} to be consistent with the rest
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
184 of Octave which prints the variable name to be displayed followed by the value.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
185
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
186 To be consistent with the Octave graphic handle classes, a class should also
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
187 define the @code{get} and @code{set} methods. The @code{get} method accepts
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
188 one or two arguments. The first argument is an object of the appropriate
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
189 class. If no second argument is given then the method should return a
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
190 structure with all the properties of the class. If the optional second
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
191 argument is given it should be a property name and the specified property
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
192 should be retrieved.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
193
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
194 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
195 @EXAMPLEFILE(@polynomial/get.m)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
196 @end example
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
197
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
198 @noindent
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
199 Similarly, the first argument to the @code{set} method should be an object and
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
200 any additional arguments should be property/value pairs.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
201
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
202 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
203 @EXAMPLEFILE(@polynomial/set.m)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
204 @end example
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
205
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
206 @noindent
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
207 Note that Octave does not implement pass by reference; Therefore, to modify an
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
208 object requires an assignment statement using the return value from the
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
209 @code{set} method.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
210
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
211 @example
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
212 p = set (p, "poly", [1, 0, 0, 0, 1]);
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
213 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
214
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
215 @noindent
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
216 The @code{set} method makes use of the @code{subsasgn} method of the class, and
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
217 therefore this method must also be defined. The @code{subsasgn} method is
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
218 discussed more thoroughly in the next section (@pxref{Indexing Objects}).
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
219
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
220 Finally, user classes can be considered to be a special type of a structure,
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
221 and they can be saved to a file in the same manner as a structure. For
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
222 example:
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
224 @example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
225 @group
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
226 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
227 save userclass.mat p
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
228 clear p
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
229 load userclass.mat
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
230 @end group
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
231 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
232
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
233 @noindent
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
234 All of the file formats supported by @code{save} and @code{load} are supported.
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
235 In certain circumstances a user class might contain a field that it doesn't
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
236 make sense to save, or a field that needs to be initialized before it is saved.
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
237 This can be done with the @code{saveobj} method of the class.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
238
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
239 @DOCSTRING(saveobj)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
240
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
241 @noindent
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
242 @code{saveobj} is called just prior to saving the class to a file. Similarly,
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
243 the @code{loadobj} method is called just after a class is loaded from a file,
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
244 and can be used to ensure that any removed fields are reinserted into the user
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
245 object.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
246
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
247 @DOCSTRING(loadobj)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
248
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
249 @node Indexing Objects
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
250 @section Indexing Objects
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
251
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
252 @menu
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
253 * Defining Indexing And Indexed Assignment::
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
254 * Indexed Assignment Optimization::
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
255 @end menu
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
256
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
257 @node Defining Indexing And Indexed Assignment
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
258 @subsection Defining Indexing And Indexed Assignment
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
259
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
260 Objects can be indexed with parentheses or braces, either like
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
261 @code{@var{obj}(@var{idx})} or like @code{@var{obj}@{@var{idx}@}}, or even
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
262 like @code{@var{obj}(@var{idx}).@var{field}}. However, it is up to the
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
263 programmer to decide what this indexing actually means. In the case of the
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
264 polynomial class @code{@var{p}(@var{n})} might mean either the coefficient of
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
265 the @var{n}-th power of the polynomial, or it might be the evaluation of the
19593
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 17744
diff changeset
266 polynomial at @var{n}. The meaning of this subscripted referencing is
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
267 determined by the @code{subsref} method.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
268
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
269 @DOCSTRING(subsref)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
270
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
271 For example, this class uses the convention that indexing with @qcode{"()"}
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
272 evaluates the polynomial and indexing with @qcode{"@{@}"} returns the
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
273 @var{n}-th coefficient (of the @var{n}-th power). The code for the
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
274 @code{subsref} method looks like
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
275
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
276 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
277 @EXAMPLEFILE(@polynomial/subsref.m)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
278 @end example
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
279
19593
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 17744
diff changeset
280 The equivalent functionality for subscripted assignments uses the
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
281 @code{subsasgn} method.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
282
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
283 @DOCSTRING(subsasgn)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
284
12534
5b9b2645db26 Add optimize_subsasgn_calls function to documentation.
Rik <octave@nomad.inbox5.com>
parents: 12448
diff changeset
285 @DOCSTRING(optimize_subsasgn_calls)
5b9b2645db26 Add optimize_subsasgn_calls function to documentation.
Rik <octave@nomad.inbox5.com>
parents: 12448
diff changeset
286
9285
226f6d001ee2 further improve the polynomial example, fix indexing
Jaroslav Hajek <highegg@gmail.com>
parents: 9251
diff changeset
287 Note that the @code{subsref} and @code{subsasgn} methods always receive the
226f6d001ee2 further improve the polynomial example, fix indexing
Jaroslav Hajek <highegg@gmail.com>
parents: 9251
diff changeset
288 whole index chain, while they usually handle only the first element. It is the
226f6d001ee2 further improve the polynomial example, fix indexing
Jaroslav Hajek <highegg@gmail.com>
parents: 9251
diff changeset
289 responsibility of these methods to handle the rest of the chain (if needed),
226f6d001ee2 further improve the polynomial example, fix indexing
Jaroslav Hajek <highegg@gmail.com>
parents: 9251
diff changeset
290 usually by forwarding it again to @code{subsref} or @code{subsasgn}.
226f6d001ee2 further improve the polynomial example, fix indexing
Jaroslav Hajek <highegg@gmail.com>
parents: 9251
diff changeset
291
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
292 If you wish to use the @code{end} keyword in subscripted expressions of an
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
293 object, then there must be an @code{end} method defined. For example, the
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
294 @code{end} method for the polynomial class might look like
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
295
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
296 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
297 @group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
298 @EXAMPLEFILE(@polynomial/end.m)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
299 @end group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
300 @end example
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
301
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
302 @noindent
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
303 which is a fairly generic @code{end} method that has a behavior similar to the
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
304 @code{end} keyword for Octave Array classes. An example using the polynomial
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
305 class is then
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
306
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
307 @example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
308 @group
14856
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents: 14846
diff changeset
309 p = polynomial ([1,2,3,4]);
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
310 p@{end-1@}
14093
050bc580cb60 doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents: 12951
diff changeset
311 @result{} 3
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
312 @end group
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
313 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
314
21076
b433f9990452 strip trailing whitespace from files
John W. Eaton <jwe@octave.org>
parents: 21072
diff changeset
315 Objects can also be used themselves as the index in a subscripted expression
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
316 and this is controlled by the @code{subsindex} function.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
317
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
318 @DOCSTRING(subsindex)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
319
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
320 Finally, objects can be used like ranges by providing a @code{colon} method.
8223
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
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
327 Octave's ubiquitous lazily-copied pass-by-value semantics implies a problem for
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
328 performance of user-defined @code{subsasgn} methods. Imagine the following
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
329 call to @code{subsasgn}
9602
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
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
333 ss = substruct ("()", @{1@});
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
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
10846
a4f482e66b65 Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
338 @noindent
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
339 where the corresponding method looking like this:
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
340
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
341 @example
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
342 @group
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
343 function x = subsasgn (x, ss, val)
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
344 @dots{}
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
345 x.myfield (ss.subs@{1@}) = val;
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
346 endfunction
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
347 @end group
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
348 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
349
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
350 The problem is that on entry to the @code{subsasgn} method, @code{x} is still
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
351 referenced from the caller's scope, which means that the method will first need
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
352 to unshare (copy) @code{x} and @code{x.myfield} before performing the
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
353 assignment. Upon completing the call, unless an error occurs, the result is
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
354 immediately assigned to @code{x} in the caller's scope, so that the previous
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
355 value of @code{x.myfield} is forgotten. Hence, the Octave language implies a
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
356 copy of N elements (N being the size of @code{x.myfield}), where modifying just
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
357 a single element would actually suffice. In other words, a constant-time
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
358 operation is degraded to linear-time one. This may be a real problem for user
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
359 classes that intrinsically store large arrays.
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
360
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
361 To partially solve the problem Octave uses a special optimization for
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
362 user-defined @code{subsasgn} methods coded as m-files. When the method gets
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
363 called as a result of the built-in assignment syntax (not a direct
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
364 @code{subsasgn} call as shown above), i.e., @w{@code{x(1) = 1}}, @b{AND} if
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
365 the @code{subsasgn} method is declared with identical input and output
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
366 arguments, as in the example above, then Octave will ignore the copy of
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
367 @code{x} inside the caller's scope; therefore, any changes made to @code{x}
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
368 during the method execution will directly affect the caller's copy as well.
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
369 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
370 element takes constant time.
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
371
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
372 It is important to understand the implications that this optimization brings.
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
373 Since no extra copy of @code{x} will exist in the caller's scope, it is
10846
a4f482e66b65 Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
374 @emph{solely} the callee's responsibility to not leave @code{x} in an invalid
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
375 state if an error occurs during the execution. Also, if the method partially
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
376 changes @code{x} and then errors out, the changes @emph{will} affect @code{x}
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
377 in the caller's scope. Deleting or completely replacing @code{x} inside
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
378 subsasgn will not do anything, however, only indexed assignments matter.
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
379
10846
a4f482e66b65 Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
380 Since this optimization may change the way code works (especially if badly
a4f482e66b65 Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents: 10791
diff changeset
381 written), a built-in variable @code{optimize_subsasgn_calls} is provided to
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
382 control it. It is on by default. Another way to avoid the optimization is to
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
383 declare subsasgn methods with different output and input arguments like this:
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
384
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
385 @example
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
386 @group
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
387 function y = subsasgn (x, ss, val)
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
388 @dots{}
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
389 endfunction
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
390 @end group
9602
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
391 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents: 9285
diff changeset
392
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
393 @node Overloading Objects
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
394 @section Overloading Objects
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
395
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
396 @menu
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
397 * Function Overloading::
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
398 * Operator Overloading::
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
399 * Precedence of Objects::
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
400 @end menu
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 @node Function Overloading
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
403 @subsection Function Overloading
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
404
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
405 Any Octave function can be overloaded, and this allows an object-specific
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
406 version of a function to be called as needed. A pertinent example for the
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
407 polynomial class might be to overload the @code{polyval} function.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
408
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
409 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
410 @group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
411 @EXAMPLEFILE(@polynomial/polyval.m)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
412 @end group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
413 @end example
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
414
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
415 This function just hands off the work to the normal Octave @code{polyval}
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
416 function. Another interesting example of an overloaded function for the
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
417 polynomial class is the @code{plot} function.
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
418
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
419 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
420 @group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
421 @EXAMPLEFILE(@polynomial/plot.m)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
422 @end group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
423 @end example
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
424
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
425 @noindent
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
426 which allows polynomials to be plotted in the domain near the region of the
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
427 roots of the polynomial.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
428
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
429 Functions that are of particular interest for overloading are the class
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
430 conversion functions such as @code{double}. Overloading these functions allows
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
431 the @code{cast} function to work with a user class. It can also can aid in the
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
432 use of a class object with methods and functions from other classes since the
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
433 object can be transformed to the requisite input form for the new function.
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
434 An example @code{double} function for the polynomial class might look like
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
435
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
436 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
437 @group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
438 @EXAMPLEFILE(@polynomial/double.m)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
439 @end group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
440 @end example
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
441
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
442 @node Operator Overloading
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
443 @subsection Operator Overloading
11403
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
444 @cindex addition
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
445 @cindex and operator
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
446 @cindex arithmetic operators
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
447 @cindex boolean expressions
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
448 @cindex boolean operators
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
449 @cindex comparison expressions
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
450 @cindex complex-conjugate transpose
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
451 @cindex division
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
452 @cindex equality operator
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
453 @cindex equality, tests for
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
454 @cindex exponentiation
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
455 @cindex expressions, boolean
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
456 @cindex expressions, comparison
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
457 @cindex expressions, logical
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
458 @cindex greater than operator
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
459 @cindex Hermitian operator
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
460 @cindex less than operator
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
461 @cindex logical expressions
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
462 @cindex logical operators
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
463 @cindex matrix multiplication
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
464 @cindex multiplication
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
465 @cindex negation
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
466 @cindex not operator
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
467 @cindex operators, arithmetic
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
468 @cindex operators, boolean
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
469 @cindex operators, logical
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
470 @cindex operators, relational
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
471 @cindex or operator
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
472 @cindex quotient
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
473 @cindex relational operators
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
474 @cindex subtraction
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
475 @cindex tests for equality
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
476 @cindex transpose
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
477 @cindex transpose, complex-conjugate
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
478 @cindex unary minus
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
479
15568
38e64d9f0fda doc: Workaround text overlap in pdf documentation caused by bug in Texinfo.
Rik <rik@octave.org>
parents: 14856
diff changeset
480 @c Need at least one plaintext sentence here between the @node and @float
19593
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 17744
diff changeset
481 @c table below or the two will overlap due to a bug in Texinfo.
15568
38e64d9f0fda doc: Workaround text overlap in pdf documentation caused by bug in Texinfo.
Rik <rik@octave.org>
parents: 14856
diff changeset
482 @c This is not our fault; this *is* a ridiculous kluge.
38e64d9f0fda doc: Workaround text overlap in pdf documentation caused by bug in Texinfo.
Rik <rik@octave.org>
parents: 14856
diff changeset
483 The following table shows, for each built-in numerical operation, the
38e64d9f0fda doc: Workaround text overlap in pdf documentation caused by bug in Texinfo.
Rik <rik@octave.org>
parents: 14856
diff changeset
484 corresponding function name to use when providing an overloaded method for a
38e64d9f0fda doc: Workaround text overlap in pdf documentation caused by bug in Texinfo.
Rik <rik@octave.org>
parents: 14856
diff changeset
485 user class.
38e64d9f0fda doc: Workaround text overlap in pdf documentation caused by bug in Texinfo.
Rik <rik@octave.org>
parents: 14856
diff changeset
486
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
487 @float Table,tab:overload_ops
11403
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
488 @opindex +
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
489 @opindex -
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
490 @opindex .*
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
491 @opindex *
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
492 @opindex ./
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
493 @opindex /
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
494 @opindex .\
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
495 @opindex \
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
496 @opindex .^
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
497 @opindex ^
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
498 @opindex <
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
499 @opindex <=
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
500 @opindex >
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
501 @opindex >=
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
502 @opindex ==
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
503 @opindex !=
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
504 @opindex ~=
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
505 @opindex &
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
506 @opindex |
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
507 @opindex !
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
508 @opindex '
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
509 @opindex .'
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
510 @opindex :
b8b08b1ac21f Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents: 11377
diff changeset
511 @opindex <
8286
6f2d95255911 fix @seealso references to point to existing anchors
Thorsten Meyer <thorsten.meyier@gmx.de>
parents: 8256
diff changeset
512
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
513 @tex
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
514 \vskip 6pt
19593
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 17744
diff changeset
515 {\hbox to \hsize {\hfill\vbox{\offinterlineskip \tabskip=0pt
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
516 \halign{
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
517 \vrule height2.0ex depth1.ex width 0.6pt #\tabskip=0.3em &
19593
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 17744
diff changeset
518 # \hfil & \vrule # & # \hfil & \vrule # & # \hfil & # \vrule
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
519 width 0.6pt \tabskip=0pt\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
520 \noalign{\hrule height 0.6pt}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
521 & Operation && Method && Description &\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
522 \noalign{\hrule}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
523 & $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
524 & $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
525 & $+ a$ && uplus (a) && Unary addition operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
526 & $- a$ && uminus (a) && Unary subtraction operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
527 & $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
528 & $a * b$ && mtimes (a, b) && Matrix multiplication operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
529 & $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
530 & $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
531 & $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
532 & $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
533 & $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
534 & $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
535 & $a < b$ && lt (a, b) && Less than operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
536 & $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
537 & $a > b$ && gt (a, b) && Greater than operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
538 & $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
539 & $a == b$ && eq (a, b) && Equal to operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
540 & $a != b$ && ne (a, b) && Not equal to operator&\cr
14808
f06a16021024 doc: trivial doc fix
John W. Eaton <jwe@octave.org>
parents: 14805
diff changeset
541 & $a \& b$ && and (a, b) && Logical and operator&\cr
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
542 & $a | b$ && or (a, b) && Logical or operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
543 & $! b$ && not (a) && Logical not operator&\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
544 & $a'$ && ctranspose (a) && Complex conjugate transpose operator &\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
545 & $a.'$ && transpose (a) && Transpose operator &\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
546 & $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
547 & $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
548 & $[a, b]$ && horzcat (a, b) && Horizontal concatenation operator &\cr
17ce09c3d030 Cleanup oop.texi
Rik <rdrider0-list@yahoo.com>
parents: 8347
diff changeset
549 & $[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
550 & $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
551 & $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
552 & $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
553 & {\it display} && display (a) && Commandline display function &\cr
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
554 \noalign{\hrule height 0.6pt}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
555 }}\hfill}}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
556 @end tex
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
557 @ifnottex
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
558 @multitable @columnfractions .1 .20 .20 .40 .1
11447
76f15f3da207 Use @headitem macro to create column heads for @multitable entries.
Rik <octave@nomad.inbox5.com>
parents: 11403
diff changeset
559 @headitem @tab Operation @tab Method @tab Description @tab
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
560 @item @tab a + b @tab plus (a, b) @tab Binary addition @tab
11377
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
561 @item @tab a - b @tab minus (a, b) @tab Binary subtraction operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
562 @item @tab + a @tab uplus (a) @tab Unary addition operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
563 @item @tab - a @tab uminus (a) @tab Unary subtraction operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
564 @item @tab a .* b @tab times (a, b) @tab Element-wise multiplication operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
565 @item @tab a * b @tab mtimes (a, b) @tab Matrix multiplication operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
566 @item @tab a ./ b @tab rdivide (a, b) @tab Element-wise right division operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
567 @item @tab a / b @tab mrdivide (a, b) @tab Matrix right division operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
568 @item @tab a .\ b @tab ldivide (a, b) @tab Element-wise left division operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
569 @item @tab a \ b @tab mldivide (a, b) @tab Matrix left division operator @tab
12951
818299a39ae1 oop.txi: Fix incorrect names for power and mpower operators
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents: 12534
diff changeset
570 @item @tab a .^ b @tab power (a, b) @tab Element-wise power operator @tab
818299a39ae1 oop.txi: Fix incorrect names for power and mpower operators
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents: 12534
diff changeset
571 @item @tab a ^ b @tab mpower (a, b) @tab Matrix power operator @tab
11377
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
572 @item @tab a < b @tab lt (a, b) @tab Less than operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
573 @item @tab a <= b @tab le (a, b) @tab Less than or equal to operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
574 @item @tab a > b @tab gt (a, b) @tab Greater than operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
575 @item @tab a >= b @tab ge (a, b) @tab Greater than or equal to operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
576 @item @tab a == b @tab eq (a, b) @tab Equal to operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
577 @item @tab a != b @tab ne (a, b) @tab Not equal to operator @tab
14808
f06a16021024 doc: trivial doc fix
John W. Eaton <jwe@octave.org>
parents: 14805
diff changeset
578 @item @tab a & b @tab and (a, b) @tab Logical and operator @tab
11377
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
579 @item @tab a | b @tab or (a, b) @tab Logical or operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
580 @item @tab ! b @tab not (a) @tab Logical not operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
581 @item @tab a' @tab ctranspose (a) @tab Complex conjugate transpose operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
582 @item @tab a.' @tab transpose (a) @tab Transpose operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
583 @item @tab a : b @tab colon (a, b) @tab Two element range operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
584 @item @tab a : b : c @tab colon (a, b, c) @tab Three element range operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
585 @item @tab [a, b] @tab horzcat (a, b) @tab Horizontal concatenation operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
586 @item @tab [a; b] @tab vertcat (a, b) @tab Vertical concatenation operator @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
587 @item @tab a(s_1, @dots{}, s_n) @tab subsref (a, s) @tab Subscripted reference @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
588 @item @tab a(s_1, @dots{}, s_n) = b @tab subsasgn (a, s, b) @tab Subscripted assignment @tab
473e4adaa5a2 oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents: 10846
diff changeset
589 @item @tab b (a) @tab subsindex (a) @tab Convert to zero-based index @tab
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
590 @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
591 @end multitable
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
592 @end ifnottex
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
593 @caption{Available overloaded operators and their corresponding class method}
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
594 @end float
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
595
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
596 An example @code{mtimes} method for the polynomial class might look like
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
597
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
598 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
599 @group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
600 @EXAMPLEFILE(@polynomial/mtimes.m)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
601 @end group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
602 @end example
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
603
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
604 @node Precedence of Objects
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
605 @subsection Precedence of Objects
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
606
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
607 Many functions and operators take two or more arguments and the situation can
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
608 easily arise where these functions are called with objects of different
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
609 classes. It is therefore necessary to determine the precedence of which method
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
610 from which class to call when there are mixed objects given to a function or
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
611 operator. To do this the @code{superiorto} and @code{inferiorto} functions can
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
612 be used
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
613
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
614 @DOCSTRING(superiorto)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
615
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
616 @DOCSTRING(inferiorto)
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
617
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
618 With the polynomial class, consider the case
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
619
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
620 @example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
621 2 * polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
622 @end example
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
623
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
624 @noindent
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
625 that mixes an object of the class @qcode{"double"} with an object of the class
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
626 @qcode{"polynomial"}. In this case the return type should be
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
627 @qcode{"polynomial"} and so the @code{superiorto} function is used in the class
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
628 constructor. In particular the polynomial class constructor would be modified
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
629 to
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
630
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
631 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
632 @EXAMPLEFILE(@polynomial/polynomial_superiorto.m)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
633 @end example
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
634
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
635 Note that user classes @emph{always} have higher precedence than built-in
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
636 Octave types. Thus, marking the polynomial class higher than the
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
637 @qcode{"double"} class is not actually necessary.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
638
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
639 When confronted with two objects of equal precedence, Octave will use the
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
640 method of the object that appears first in the list of arguments.
8223
0c91b9a17dcf Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff changeset
641
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
642 @node Inheritance and Aggregation
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
643 @section Inheritance and Aggregation
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
644
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
645 Using classes to build new classes is supported by Octave through the use of
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
646 both inheritance and aggregation.
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
647
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
648 Class inheritance is provided by Octave using the @code{class} function in the
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
649 class constructor. As in the case of the polynomial class, the Octave
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
650 programmer will create a structure that contains the data fields required by
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
651 the class, and then call the @code{class} function to indicate that an object
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
652 is to be created from the structure. Creating a child of an existing object is
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
653 done by creating an object of the parent class and providing that object as the
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
654 third argument of the class function.
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
655
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
656 This is most easily demonstrated by example. Suppose the programmer needs a
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
657 FIR filter, i.e., a filter with a numerator polynomial but a denominator of 1.
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
658 In traditional Octave programming this would be performed as follows.
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
659
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
660 @example
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
661 @group
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
662 octave:1> x = [some data vector];
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
663 octave:2> n = [some coefficient vector];
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
664 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
665 @end group
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
666 @end example
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
667
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
668 The equivalent behavior can be implemented as a class @@FIRfilter. The
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
669 constructor for this class is the file @file{FIRfilter.m} in the class
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
670 directory @file{@@FIRfilter}.
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
671
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
672 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
673 @EXAMPLEFILE(@FIRfilter/FIRfilter.m)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
674 @end example
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
675
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
676 As before, the leading comments provide documentation for the class
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
677 constructor. This constructor is very similar to the polynomial class
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
678 constructor, except that a polynomial object is passed as the third argument to
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
679 the @code{class} function, telling Octave that the @w{FIRfilter} class will be
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
680 derived from the polynomial class. The FIR filter class itself does not have
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
681 any data fields, but it must provide a struct to the @code{class} function.
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
682 Given that the @@polynomial constructor will add an element named
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
683 @var{polynomial} to the object struct, the @@FIRfilter just initializes a
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
684 struct with a dummy field @var{polynomial} which will later be overwritten.
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
685
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
686 Note that the sample code always provides for the case in which no arguments
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
687 are supplied. This is important because Octave will call a constructor with
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
688 no arguments when loading objects from saved files in order to determine the
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
689 inheritance structure.
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
690
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
691 A class may be a child of more than one class (@pxref{XREFclass,,class}), and
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
692 inheritance may be nested. There is no limitation to the number of parents or
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
693 the level of nesting other than memory or other physical issues.
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
694
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
695 As before, a class requires a @code{display} method. A simple example might be
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
696
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
697 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
698 @group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
699 @EXAMPLEFILE(@FIRfilter/display.m)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
700 @end group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
701 @end example
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
702
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
703 Note that the @w{FIRfilter}'s display method relies on the display method
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
704 from the polynomial class to actually display the filter coefficients.
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
705
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
706 Once a constructor and display method exist, it is possible to create an
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
707 instance of the class. It is also possible to check the class type and examine
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
708 the underlying structure.
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
709
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
710 @example
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
711 @group
14856
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents: 14846
diff changeset
712 octave:1> f = FIRfilter (polynomial ([1 1 1]/3))
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
713 f.polynomial = 0.33333 + 0.33333 * X + 0.33333 * X ^ 2
14856
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents: 14846
diff changeset
714 octave:2> class (f)
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
715 ans = FIRfilter
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
716 octave:3> isa (f, "FIRfilter")
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
717 ans = 1
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
718 octave:4> isa (f, "polynomial")
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
719 ans = 1
14856
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents: 14846
diff changeset
720 octave:5> struct (f)
19593
446c46af4b42 strip trailing whitespace from most source files
John W. Eaton <jwe@octave.org>
parents: 17744
diff changeset
721 ans =
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
722
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
723 scalar structure containing the fields:
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
724
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
725 polynomial = 0.33333 + 0.33333 * X + 0.33333 * X ^ 2
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
726 @end group
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
727 @end example
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
728
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
729 The only thing remaining to make this class usable is a method for processing
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
730 data. But before that, it is usually desirable to also have a way of changing
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
731 the data stored in a class. Since the fields in the underlying struct are
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
732 private by default, it is necessary to provide a mechanism to access the
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
733 fields. The @code{subsref} method may be used for both tasks.
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
734
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
735 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
736 @EXAMPLEFILE(@FIRfilter/subsref.m)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
737 @end example
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
738
17281
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents: 15997
diff changeset
739 The @qcode{"()"} case allows us to filter data using the polynomial provided
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
740 to the constructor.
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
741
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
742 @example
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
743 @group
14856
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents: 14846
diff changeset
744 octave:2> f = FIRfilter (polynomial ([1 1 1]/3));
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents: 14846
diff changeset
745 octave:3> x = ones (5,1);
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents: 14846
diff changeset
746 octave:4> y = f(x)
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
747 y =
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
748
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
749 0.33333
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
750 0.66667
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
751 1.00000
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
752 1.00000
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
753 1.00000
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
754 @end group
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
755 @end example
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
756
17281
bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents: 15997
diff changeset
757 The @qcode{"."} case allows us to view the contents of the polynomial field.
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
758
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
759 @example
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
760 @group
14856
c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents: 14846
diff changeset
761 octave:1> f = FIRfilter (polynomial ([1 1 1]/3));
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
762 octave:2> f.polynomial
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
763 ans = 0.33333 + 0.33333 * X + 0.33333 * X ^ 2
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
764 @end group
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
765 @end example
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
766
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
767 In order to change the contents of the object a @code{subsasgn} method is
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
768 needed. For example, the following code makes the polynomial field publicly
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
769 writable
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
770
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
771 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
772 @group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
773 @EXAMPLEFILE(@FIRfilter/subsasgn.m)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
774 @end group
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
775 @end example
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
776
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
777 @noindent
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
778 so that
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
779
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
780 @example
9758
09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents: 9752
diff changeset
781 @group
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
782 octave:1> f = FIRfilter ();
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
783 octave:2> f.polynomial = polynomial ([1 2 3])
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
784 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
785 @end group
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
786 @end example
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
787
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
788 Defining the @w{FIRfilter} class as a child of the polynomial class implies
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
789 that a @w{FIRfilter} object may be used any place that a polynomial object may
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
790 be used. This is not a normal use of a filter. It may be a more sensible
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
791 design approach to use aggregation rather than inheritance. In this case, the
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
792 polynomial is simply a field in the class structure. A class constructor for
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
793 the aggregation case might be
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
794
9906
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
795 @example
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
796 @EXAMPLEFILE(@FIRfilter/FIRfilter_aggregation.m)
8d20fb66a0dc more automake fixes
John W. Eaton <jwe@octave.org>
parents: 9758
diff changeset
797 @end example
9251
f8b8ab529913 improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents: 9245
diff changeset
798
21072
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
799 For this example only the constructor needs changing, and all other class
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming.
Rik <rik@octave.org>
parents: 21061
diff changeset
800 methods stay the same.
21061
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming.
Rik <rik@octave.org>
parents: 19697
diff changeset
801