octave: doc/interpreter/oop.txi annotate

annotate doc/interpreter/oop.txi @ 25024:3c817af70eed stable

maint: use https for all Octave project URLs * README, update-bug-status.sh, configure.ac, bugs.txi, errors.txi, func.txi, octave-cli.1, octave.1, oop.txi, preface.txi, testfun.txi, CHECKLIST, PROJECTS, be_BY.ts, de_DE.ts, en_US.ts, es_ES.ts, eu_ES.ts, fr_FR.ts, it_IT.ts, ja_JP.ts, nl_NL.ts, pt_BR.ts, pt_PT.ts, ru_RU.ts, uk_UA.ts, zh_CN.ts, main-window.cc, welcome-wizard.cc, version.cc, __unimplemented__.m, help.m, __additional_help_message__.m, bug_report.m, info.m, __publish_html_output__.m, publish.m, get_forge_pkg.m, list_forge_packages.m, test.m, test_script_example.m: Use https for all Octave project URLs under octave.org or www.gnu.org/software/octave.

author	Mike Miller <mtmiller@octave.org>
date	Tue, 27 Mar 2018 13:54:58 -0700
parents	e6b22e378389
children	6652d3823428

rev	line source
23219 3ac9f9ecfae5 maint: Update copyright dates. John W. Eaton <jwe@octave.org> parents: 23132 diff changeset	1 @c Copyright (C) 2008-2017 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
24534 194eb4bd202b maint: Update punctuation for GPL v3 license text. Rik <rik@octave.org> parents: 24510 diff changeset	6 @c Octave is free software: you can redistribute it and/or modify it
24358 3516d922b2bf Revert change to Copyright word wrapping in 907f8c3e1c8d. Rik <rik@octave.org> parents: 24357 diff changeset	7 @c under the terms of the GNU General Public License as published by
24534 194eb4bd202b maint: Update punctuation for GPL v3 license text. Rik <rik@octave.org> parents: 24510 diff changeset	8 @c the Free Software Foundation, either version 3 of the License, or
24358 3516d922b2bf Revert change to Copyright word wrapping in 907f8c3e1c8d. Rik <rik@octave.org> parents: 24357 diff changeset	9 @c (at 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
24358 3516d922b2bf Revert change to Copyright word wrapping in 907f8c3e1c8d. Rik <rik@octave.org> parents: 24357 diff changeset	11 @c Octave is distributed in the hope that it will be useful, but
3516d922b2bf Revert change to Copyright word wrapping in 907f8c3e1c8d. Rik <rik@octave.org> parents: 24357 diff changeset	12 @c WITHOUT ANY WARRANTY; without even the implied warranty of
3516d922b2bf Revert change to Copyright word wrapping in 907f8c3e1c8d. Rik <rik@octave.org> parents: 24357 diff changeset	13 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3516d922b2bf Revert change to Copyright word wrapping in 907f8c3e1c8d. Rik <rik@octave.org> parents: 24357 diff changeset	14 @c GNU General Public License 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
24534 194eb4bd202b maint: Update punctuation for GPL v3 license text. Rik <rik@octave.org> parents: 24510 diff changeset	18 @c <https://www.gnu.org/licenses/>.
8223 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::
24357 49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	44 * classdef Classes::
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	45 @end menu
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	46
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	47 @node Creating a Class
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	48 @section Creating a Class
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	49
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	50 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	51 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	52 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	53 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	54 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	55 object oriented programming are introduced.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	56
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	57 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	58 @tex
050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	59 $$
050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	60 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	61 $$
050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	62 @end tex
050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	63 @ifnottex
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	64
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	65 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	66 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	67 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	68
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	69 @end ifnottex
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	70 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	71 where
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	72 @tex
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	73 $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	74 @end tex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	75 @ifnottex
21530 7c143e73e921 doc: Don't create end-of-sentence period with "etc." in Texinfo. Rik <rik@octave.org> parents: 21076 diff changeset	76 a0, a1, etc.@: are real scalars.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	77 @end ifnottex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	78 Thus the polynomial can be represented by a vector
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	79
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	80 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	81 a = [a0, a1, a2, @dots{}, an];
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	82 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	83
24510 a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24360 diff changeset	84 @opindex @@ class methods
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	85 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	86 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	87 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	88 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	89 @file{@@polynomial} directory.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	90
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	91 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	92 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	93 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	94 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	95
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	96 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	97 @EXAMPLEFILE(@polynomial/polynomial.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	98 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	99
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	100 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	101 @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	102 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	103 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	104
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	105 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	106 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	107 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	108
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	109 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	110 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	111 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	112 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	113 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	114 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	115 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	116 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	117 of a class.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	118
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	119 The same specification mechanism can be used wherever Octave expects a function
23410 705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	120 name. For example @code{type @@polynomial/disp} will print the code of the
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	121 @code{disp} method of the polynomial class to the screen, and
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	122 @code{dbstop @@polynomial/disp} will set a breakpoint at the first executable
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	123 line of the @code{disp} method of the polynomial class.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	124
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	125 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	126 @code{isa} functions can be used. For example:
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	127
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	128 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	129 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	130 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	131 isobject (p)
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 isa (p, "polynomial")
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	134 @result{} 1
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	135 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	136 @end example
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 @DOCSTRING(isobject)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	139
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	140 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	141 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	142 function.
8223 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 @DOCSTRING(methods)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	145
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	146 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	147 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	148 @code{ismethod} function can be used.
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 @DOCSTRING(ismethod)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	151
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	152 @noindent
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	153 For example:
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	154
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	155 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	156 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	157 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	158 ismethod (p, "roots")
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	159 @result{} 1
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	160 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	161 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	162
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	163 @node Class Methods
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	164 @section Class Methods
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	165
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	166 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	167 allow the contents of the classes to be queried and set. The most basic of
23410 705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	168 these is the @code{disp} method. The @code{disp} method is used by Octave
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	169 whenever a class should be displayed on the screen. Usually this is the result
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	170 of an Octave expression that doesn't end with a semicolon. If this method is
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	171 not defined, then Octave won't print anything when displaying the contents of a
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	172 class which can be confusing.
8223 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
23410 705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	175 An example of a @code{disp} method for the polynomial class might be
8223 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
23371 a5280a05b188 doc: Change example old-style class code to overload disp rather than display. Rik <rik@octave.org> parents: 23220 diff changeset	178 @EXAMPLEFILE(@polynomial/disp.m)
9906 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
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	181 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	182 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	183 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	184 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	185 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	186 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	187 should be retrieved.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	188
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	189 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	190 @EXAMPLEFILE(@polynomial/get.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	191 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	192
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	193 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	194 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	195 any additional arguments should be property/value pairs.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	196
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	197 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	198 @EXAMPLEFILE(@polynomial/set.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	199 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	200
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	201 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	202 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	203 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	204 @code{set} method.
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 @example
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	207 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	208 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	209
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	210 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	211 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	212 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	213 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	214
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	215 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	216 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	217 example:
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	218
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	219 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	220 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	221 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	222 save userclass.mat p
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	223 clear p
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	224 load userclass.mat
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	225 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	226 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	227
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	228 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	229 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	230 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	231 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	232 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	233
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	234 @DOCSTRING(saveobj)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	235
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	236 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	237 @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	238 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	239 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	240 object.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	241
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	242 @DOCSTRING(loadobj)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	243
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	244 @node Indexing Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	245 @section Indexing Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	246
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	247 @menu
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	248 * Defining Indexing And Indexed Assignment::
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	249 * Indexed Assignment Optimization::
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	250 @end menu
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	251
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	252 @node Defining Indexing And Indexed Assignment
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	253 @subsection Defining Indexing And Indexed Assignment
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	254
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	255 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	256 @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	257 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	258 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	259 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	260 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	261 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	262 determined by the @code{subsref} method.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	263
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	264 @DOCSTRING(subsref)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	265
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	266 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	267 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	268 @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	269 @code{subsref} method looks like
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	270
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	271 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	272 @EXAMPLEFILE(@polynomial/subsref.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	273 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	274
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 17744 diff changeset	275 The equivalent functionality for subscripted assignments uses the
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	276 @code{subsasgn} method.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	277
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	278 @DOCSTRING(subsasgn)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	279
12534 5b9b2645db26 Add optimize_subsasgn_calls function to documentation. Rik <octave@nomad.inbox5.com> parents: 12448 diff changeset	280 @DOCSTRING(optimize_subsasgn_calls)
5b9b2645db26 Add optimize_subsasgn_calls function to documentation. Rik <octave@nomad.inbox5.com> parents: 12448 diff changeset	281
9285 226f6d001ee2 further improve the polynomial example, fix indexing Jaroslav Hajek <highegg@gmail.com> parents: 9251 diff changeset	282 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	283 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	284 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	285 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	286
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	287 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	288 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	289 @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	290
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	291 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	292 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	293 @EXAMPLEFILE(@polynomial/end.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	294 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	295 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	296
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	297 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	298 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	299 @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	300 class is then
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 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	303 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	304 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	305 p@{end-1@}
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	306 @result{} 3
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	307 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	308 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	309
21076 b433f9990452 strip trailing whitespace from files John W. Eaton <jwe@octave.org> parents: 21072 diff changeset	310 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	311 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	312
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	313 @DOCSTRING(subsindex)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	314
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	315 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	316
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	317 @DOCSTRING(colon)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	318
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	319 @node Indexed Assignment Optimization
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	320 @subsection Indexed Assignment Optimization
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	321
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	322 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	323 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	324 call to @code{subsasgn}
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	325
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	326 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	327 @group
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	328 ss = substruct ("()", @{1@});
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	329 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	330 @end group
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	331 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	332
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	333 @noindent
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	334 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	335
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	336 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	337 @group
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	338 function x = subsasgn (x, ss, val)
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	339 @dots{}
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	340 x.myfield (ss.subs@{1@}) = val;
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	341 endfunction
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	342 @end group
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	343 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	344
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	345 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	346 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	347 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	348 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	349 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	350 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	351 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	352 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	353 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	354 classes that intrinsically store large arrays.
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	355
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	356 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	357 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	358 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	359 @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	360 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	361 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	362 @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	363 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	364 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	365 element takes constant time.
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	366
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	367 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	368 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	369 @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	370 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	371 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	372 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	373 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	374
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	375 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	376 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	377 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	378 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	379
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	380 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	381 @group
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	382 function y = subsasgn (x, ss, val)
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	383 @dots{}
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	384 endfunction
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	385 @end group
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	386 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	387
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	388 @node Overloading Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	389 @section Overloading Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	390
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	391 @menu
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	392 * Function Overloading::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	393 * Operator Overloading::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	394 * Precedence of Objects::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	395 @end menu
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	396
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	397 @node Function Overloading
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	398 @subsection Function Overloading
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	399
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	400 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	401 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	402 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	403
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	404 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	405 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	406 @EXAMPLEFILE(@polynomial/polyval.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	407 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	408 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	409
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	410 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	411 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	412 polynomial class is the @code{plot} function.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	413
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	414 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	415 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	416 @EXAMPLEFILE(@polynomial/plot.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	417 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	418 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	419
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	420 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	421 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	422 roots of the polynomial.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	423
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	424 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	425 conversion functions such as @code{double}. Overloading these functions allows
24575 93714122ed59 doc: Fixes for signal, image, audio, and OOP chapters (bug #52844). Rik <rik@octave.org> parents: 24359 diff changeset	426 the @code{cast} function to work with a user class. It can also aid in the
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	427 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	428 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	429 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	430
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	431 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	432 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	433 @EXAMPLEFILE(@polynomial/double.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	434 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	435 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	436
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	437 @node Operator Overloading
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	438 @subsection Operator Overloading
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	439 @cindex addition
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	440 @cindex and operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	441 @cindex arithmetic operators
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	442 @cindex boolean expressions
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	443 @cindex boolean operators
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	444 @cindex comparison expressions
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	445 @cindex complex-conjugate transpose
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	446 @cindex division
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	447 @cindex equality operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	448 @cindex equality, tests for
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	449 @cindex exponentiation
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	450 @cindex expressions, boolean
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	451 @cindex expressions, comparison
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	452 @cindex expressions, logical
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	453 @cindex greater than operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	454 @cindex Hermitian operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	455 @cindex less than operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	456 @cindex logical expressions
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	457 @cindex logical operators
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	458 @cindex matrix multiplication
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	459 @cindex multiplication
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	460 @cindex negation
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	461 @cindex not operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	462 @cindex operators, arithmetic
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	463 @cindex operators, boolean
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	464 @cindex operators, logical
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	465 @cindex operators, relational
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	466 @cindex or operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	467 @cindex quotient
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	468 @cindex relational operators
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	469 @cindex subtraction
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	470 @cindex tests for equality
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	471 @cindex transpose
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	472 @cindex transpose, complex-conjugate
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	473 @cindex unary minus
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	474
15568 38e64d9f0fda doc: Workaround text overlap in pdf documentation caused by bug in Texinfo. Rik <rik@octave.org> parents: 14856 diff changeset	475 @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	476 @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	477 @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	478 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	479 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	480 user class.
38e64d9f0fda doc: Workaround text overlap in pdf documentation caused by bug in Texinfo. Rik <rik@octave.org> parents: 14856 diff changeset	481
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	482 @float Table,tab:overload_ops
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	483 @opindex +
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	484 @opindex -
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	485 @opindex .*
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	486 @opindex *
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	487 @opindex ./
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 !
24550 966c3283a164 doc: Fix appearance of '.' and "'" in Operator Index (bug #52813). Rik <rik@octave.org> parents: 24534 diff changeset	503 @opindex @code{'}
966c3283a164 doc: Fix appearance of '.' and "'" in Operator Index (bug #52813). Rik <rik@octave.org> parents: 24534 diff changeset	504 @opindex @code{.'}
11403 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 <
8286 6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	507
23131 a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	508 @multitable {@code{a(s@math{_1},@dots{},s@math{_n}) = b}} {@code{subsasgn (a, s, b)}} {Complex conjugate transpose}
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	509 @headitem Operation @tab Method @tab Description
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	510 @item @code{a + b} @tab @code{plus (a, b)} @tab Binary addition
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	511 @item @code{a - b} @tab @code{minus (a, b)} @tab Binary subtraction
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	512 @item @code{+a} @tab @code{uplus (a)} @tab Unary addition
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	513 @item @code{-a} @tab @code{uminus (a)} @tab Unary subtraction
23132 0f2582425a9e doc: Correct two entries in Table 34.1 (bug #50203). Rik <rik@octave.org> parents: 23131 diff changeset	514 @item @code{a .* b} @tab @code{times (a, b)} @tab Element-wise multiplication
23131 a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	515 @item @code{a * b} @tab @code{mtimes (a, b)} @tab Matrix multiplication
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	516 @item @code{a ./ b} @tab @code{rdivide (a, b)} @tab Element-wise right division
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	517 @item @code{a / b} @tab @code{mrdivide (a, b)} @tab Matrix right division
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	518 @item @code{a .\ b} @tab @code{ldivide (a, b)} @tab Element-wise left division
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	519 @item @code{a \ b} @tab @code{mldivide (a, b)} @tab Matrix left division
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	520 @item @code{a .^ b} @tab @code{power (a, b)} @tab Element-wise power
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	521 @item @code{a ^ b} @tab @code{mpower (a, b)} @tab Matrix power
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	522 @item @code{a < b} @tab @code{lt (a, b)} @tab Less than
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	523 @item @code{a <= b} @tab @code{le (a, b)} @tab Less than or equal to
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	524 @item @code{a > b} @tab @code{gt (a, b)} @tab Greater than
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	525 @item @code{a >= b} @tab @code{ge (a, b)} @tab Greater than or equal to
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	526 @item @code{a == b} @tab @code{eq (a, b)} @tab Equal to
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	527 @item @code{a != b} @tab @code{ne (a, b)} @tab Not equal to
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	528 @item @code{a & b} @tab @code{and (a, b)} @tab Logical and
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	529 @item @code{a \| b} @tab @code{or (a, b)} @tab Logical or
23132 0f2582425a9e doc: Correct two entries in Table 34.1 (bug #50203). Rik <rik@octave.org> parents: 23131 diff changeset	530 @item @code{!a} @tab @code{not (a)} @tab Logical not
23131 a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	531 @item @code{a'} @tab @code{ctranspose (a)} @tab Complex conjugate transpose
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	532 @item @code{a.'} @tab @code{transpose (a)} @tab Transpose
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	533 @item @code{a:b} @tab @code{colon (a, b)} @tab Two element range
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	534 @item @code{a:b:c} @tab @code{colon (a, b, c)} @tab Three element range
24359 1da659b26bec doc: grammarcheck of Object Oriented Programming chapter in manual. Rik <rik@octave.org> parents: 24358 diff changeset	535 @item @code{[a, b]} @tab @code{horzcat (a, b)} @tab Horizontal concatenation
23131 a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	536 @item @code{[a; b]} @tab @code{vertcat (a, b)} @tab Vertical concatenation
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	537 @item @code{a(s@math{_1},@dots{},s@math{_n})} @tab @code{subsref (a, s)} @tab Subscripted reference
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	538 @item @code{a(s@math{_1},@dots{},s@math{_n}) = b} @tab @code{subsasgn (a, s, b)} @tab Subscripted assignment
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	539 @item @code{b(a)} @tab @code{subsindex (a)} @tab Convert object to index
23410 705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	540 @item @code{disp} @tab @code{disp (a)} @tab Object display
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	541 @end multitable
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	542 @caption{Available overloaded operators and their corresponding class method}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	543 @end float
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	544
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	545 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	546
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	547 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	548 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	549 @EXAMPLEFILE(@polynomial/mtimes.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	550 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	551 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	552
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	553 @node Precedence of Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	554 @subsection Precedence of Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	555
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	556 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	557 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	558 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	559 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	560 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	561 be used
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	562
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	563 @DOCSTRING(superiorto)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	564
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	565 @DOCSTRING(inferiorto)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	566
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	567 With the polynomial class, consider the case
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	568
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	569 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	570 2 * polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	571 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	572
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	573 @noindent
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	574 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	575 @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	576 @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	577 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	578 to
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	579
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	580 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	581 @EXAMPLEFILE(@polynomial/polynomial_superiorto.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	582 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	583
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	584 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	585 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	586 @qcode{"double"} class is not actually necessary.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	587
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	588 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	589 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	590
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	591 @node Inheritance and Aggregation
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	592 @section Inheritance and Aggregation
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	593
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	594 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	595 both inheritance and aggregation.
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	596
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	597 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	598 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	599 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	600 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	601 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	602 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	603 third argument of the class function.
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	604
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	605 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	606 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	607 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	608
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	609 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	610 @group
23410 705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	611 >> x = [some data vector];
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	612 >> n = [some coefficient vector];
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	613 >> 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	614 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	615 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	616
23410 705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	617 The equivalent behavior can be implemented as a class @code{@@FIRfilter}. The
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	618 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	619 directory @file{@@FIRfilter}.
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	620
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	621 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	622 @EXAMPLEFILE(@FIRfilter/FIRfilter.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	623 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	624
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	625 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	626 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	627 constructor, except that a polynomial object is passed as the third argument to
23410 705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	628 the @code{class} function, telling Octave that the @code{FIRfilter} class will
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	629 be derived from the polynomial class. The FIR filter class itself does not
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	630 have any data fields, but it must provide a struct to the @code{class}
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	631 function. Given that the @code{@@polynomial} constructor will add an element
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	632 named @var{polynomial} to the object struct, the @code{@@FIRfilter} just
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	633 initializes a struct with a dummy field @var{polynomial} which will later be
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	634 overwritten.
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	635
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	636 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	637 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	638 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	639 inheritance structure.
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	640
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	641 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	642 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	643 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	644
23410 705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	645 For the @code{FIRfilter} class, more control about the object display is
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	646 desired. Therefore, the @code{display} method rather than the @code{disp}
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	647 method is overloaded (@pxref{Class Methods}). A simple example might be
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	648
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	649 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	650 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	651 @EXAMPLEFILE(@FIRfilter/display.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	652 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	653 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	654
23410 705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	655 Note that the @code{FIRfilter}'s display method relies on the @code{disp}
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	656 method from the @code{polynomial} class to actually display the filter
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	657 coefficients. Furthermore, note that in the @code{display} method it makes
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	658 sense to start the method with the line
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	659 @code{@code{printf ("%s =", inputname (1))}} to be consistent with the
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	660 rest of Octave which prints the variable name to be displayed followed by the
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	661 value. In general it is not recommended to overload the @code{display}
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	662 function.
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	663
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	664 @DOCSTRING(display)
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	665
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	666 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	667 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	668 the underlying structure.
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	669
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	670 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	671 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	672 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	673 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	674 octave:2> class (f)
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	675 ans = FIRfilter
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	676 octave:3> isa (f, "FIRfilter")
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	677 ans = 1
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	678 octave:4> isa (f, "polynomial")
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	679 ans = 1
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	680 octave:5> struct (f)
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 17744 diff changeset	681 ans =
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	682
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	683 scalar structure containing the fields:
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	684
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	685 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	686 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	687 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	688
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	689 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	690 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	691 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	692 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	693 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	694
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	695 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	696 @EXAMPLEFILE(@FIRfilter/subsref.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	697 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	698
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 15997 diff changeset	699 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	700 to the constructor.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	701
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	702 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	703 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	704 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	705 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	706 octave:4> y = f(x)
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	707 y =
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	708
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	709 0.33333
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	710 0.66667
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	711 1.00000
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	712 1.00000
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	713 1.00000
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	714 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	715 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	716
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 15997 diff changeset	717 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	718
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	719 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	720 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	721 octave:1> f = FIRfilter (polynomial ([1 1 1]/3));
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	722 octave:2> f.polynomial
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	723 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	724 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	725 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	726
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	727 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	728 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	729 writable
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	730
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	731 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	732 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	733 @EXAMPLEFILE(@FIRfilter/subsasgn.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	734 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	735 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	736
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	737 @noindent
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	738 so that
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	739
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	740 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	741 @group
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	742 octave:1> f = FIRfilter ();
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	743 octave:2> f.polynomial = polynomial ([1 2 3])
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	744 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	745 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	746 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	747
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	748 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	749 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	750 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	751 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	752 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	753 the aggregation case might be
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	754
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	755 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	756 @EXAMPLEFILE(@FIRfilter/FIRfilter_aggregation.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	757 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	758
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	759 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	760 methods stay the same.
24357 49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	761
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	762 @node classdef Classes
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	763 @section @code{classdef} Classes
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	764
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	765 Since version 4.0, Octave has limited support for @code{classdef} classes. In
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	766 contrast to the aforementioned classes, called @dfn{old style classes} in this
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	767 section, @code{classdef} classes can be defined within a single m-file. Other
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	768 innovations of @code{classdef} classes are:
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	769
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	770 @itemize @bullet
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	771 @item
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	772 @b{access rights} for properties and methods,
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	773
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	774 @item
24359 1da659b26bec doc: grammarcheck of Object Oriented Programming chapter in manual. Rik <rik@octave.org> parents: 24358 diff changeset	775 @b{static methods}, i.e., methods that are independent of an object, and
24357 49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	776
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	777 @item
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	778 the distinction between @b{value and handle classes}.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	779 @end itemize
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	780
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	781 Several features have to be added in future versions of Octave to be fully
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	782 compatible to @sc{matlab}. An overview of what is missing can be found at
25024 3c817af70eed maint: use https for all Octave project URLs Mike Miller <mtmiller@octave.org> parents: 24576 diff changeset	783 @url{https://wiki.octave.org/Classdef}.
24357 49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	784
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	785 @menu
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	786 * Creating a classdef Class::
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	787 * Properties::
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	788 * Methods::
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	789 * Inheritance::
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	790 * Value Classes vs. Handle Classes::
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	791 @end menu
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	792
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	793 @node Creating a classdef Class
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	794 @subsection Creating a @code{classdef} Class
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	795
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	796 A very basic @code{classdef} value class
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	797 (@pxref{Value Classes vs. Handle Classes}) is defined by:
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	798
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	799 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	800 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	801 classdef some_class
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	802 properties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	803 endproperties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	804
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	805 methods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	806 endmethods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	807 endclassdef
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	808 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	809 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	810
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	811
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	812
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	813 In contrast to old style classes, the @code{properties}-@code{endproperties}
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	814 block as well as the @code{methods}-@code{endmethods} block can be used to
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	815 define properties and methods of the class. Because both blocks are empty,
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	816 they can be omitted in this particular case.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	817
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	818 For simplicity, a more advanced implementation of a @code{classdef} class is
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	819 shown using the @code{polynomial} example again (@pxref{Creating a Class}):
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	820
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	821 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	822 @EXAMPLEFILE(polynomial2.m)
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	823 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	824
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	825 @noindent
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	826 An object of class @code{polynomial2} is created by calling the class
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	827 constructor:
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	828
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	829 @example
24359 1da659b26bec doc: grammarcheck of Object Oriented Programming chapter in manual. Rik <rik@octave.org> parents: 24358 diff changeset	830 @group
24357 49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	831 >> p = polynomial2 ([1, 0, 1])
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	832 @result{} p =
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	833
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	834 1 + X ^ 2
24359 1da659b26bec doc: grammarcheck of Object Oriented Programming chapter in manual. Rik <rik@octave.org> parents: 24358 diff changeset	835 @end group
24357 49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	836 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	837
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	838 @node Properties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	839 @subsection Properties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	840
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	841 All class properties must be defined within @code{properties} blocks. The
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	842 definition of a default value for a property is optional and can be omitted.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	843 The default initial value for each class property is @code{[]}.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	844
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	845 A @code{properties} block can have additional attributes to specify access
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	846 rights or to define constants:
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	847
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	848 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	849 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	850 classdef some_class
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	851 properties (Access = @var{mode})
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	852 @var{prop1}
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	853 endproperties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	854
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	855 properties (SetAccess = @var{mode}, GetAccess = @var{mode})
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	856 @var{prop2}
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	857 endproperties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	858
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	859 properties (Constant = true)
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	860 @var{prop3} = pi ()
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	861 endproperties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	862
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	863 properties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	864 @var{prop4} = 1337
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	865 endproperties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	866 endclassdef
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	867 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	868 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	869
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	870 @noindent
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	871 where @var{mode} can be one of:
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	872
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	873 @table @code
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	874 @item public
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	875 The properties can be accessed from everywhere.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	876
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	877 @item private
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	878 The properties can only be accessed from class methods. Subclasses of that
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	879 class cannot access them.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	880
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	881 @item protected
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	882 The properties can only be accessed from class methods and from subclasses
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	883 of that class.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	884 @end table
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	885
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	886 When creating an object of @code{some_class}, @var{prop1} has the default
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	887 value @code{[]} and reading from and writing to @var{prop1} is defined by
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	888 a single @var{mode}. For @var{prop2} the read and write access can be set
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	889 differently. Finally, @var{prop3} is a constant property which can only be
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	890 initialized once within the @code{properties} block.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	891
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	892 By default, in the example @var{prop4}, properties are not constant and have
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	893 public read and write access.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	894
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	895 @node Methods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	896 @subsection Methods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	897
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	898 All class methods must be defined within @code{methods} blocks. An exception
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	899 to this rule is described at the end of this subsection. Those @code{methods}
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	900 blocks can have additional attributes specifying the access rights or whether
24359 1da659b26bec doc: grammarcheck of Object Oriented Programming chapter in manual. Rik <rik@octave.org> parents: 24358 diff changeset	901 the methods are static, i.e., methods that can be called without creating an
24357 49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	902 object of that class.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	903
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	904 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	905 classdef some_class
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	906 methods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	907 function obj = some_class ()
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	908 disp ("New instance created.");
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	909 endfunction
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	910
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	911 function disp (obj)
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	912 disp ("Here is some_class.");
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	913 endfunction
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	914 endmethods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	915
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	916 methods (Access = @var{mode})
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	917 function r = func (obj, r)
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	918 r = 2 * r;
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	919 endfunction
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	920 endmethods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	921
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	922 methods (Static = true)
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	923 function c = circumference (radius)
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	924 c = 2 * pi () .* radius;
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	925 endfunction
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	926 endmethods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	927 endclassdef
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	928 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	929
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	930 The constructor of the class is declared in the @code{methods} block and must
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	931 have the same name as the class and exactly one output argument which is an
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	932 object of its class.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	933
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	934 It is also possible to overload built-in or inherited methods, like the
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	935 @code{disp} function in the example above to tell Octave how objects of
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	936 @code{some_class} should be displayed (@pxref{Class Methods}).
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	937
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	938 In general, the first argument in a method definition is always the object that
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	939 it is called from. Class methods can either be called by passing the object as
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	940 the first argument to that method or by calling the object followed by a dot
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	941 ("@code{.}") and the method's name with subsequent arguments:
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	942
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	943 @example
24359 1da659b26bec doc: grammarcheck of Object Oriented Programming chapter in manual. Rik <rik@octave.org> parents: 24358 diff changeset	944 @group
24357 49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	945 >> obj = some_class ();
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	946 New instance created.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	947 >> disp (obj); # both are
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	948 >> obj.disp (); # equal
24359 1da659b26bec doc: grammarcheck of Object Oriented Programming chapter in manual. Rik <rik@octave.org> parents: 24358 diff changeset	949 @end group
24357 49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	950 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	951
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	952 In @code{some_class}, the method @code{func} is defined within a @code{methods}
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	953 block setting the @code{Access} attribute to @var{mode}, which is one of:
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	954
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	955 @table @code
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	956 @item public
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	957 The methods can be accessed from everywhere.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	958
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	959 @item private
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	960 The methods can only be accessed from other class methods. Subclasses of that
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	961 class cannot access them.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	962
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	963 @item protected
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	964 The methods can only be accessed from other class methods and from subclasses
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	965 of that class.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	966 @end table
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	967
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	968 @noindent
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	969 The default access for methods is @code{public}.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	970
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	971 Finally, the method @code{circumference} is defined in a static @code{methods}
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	972 block and can be used without creating an object of @code{some_class}. This is
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	973 useful for methods, that do not depend on any class properties. The class name
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	974 and the name of the static method, separated by a dot ("@code{.}"), call this
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	975 static method. In contrast to non-static methods, the object is not passed as
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	976 first argument even if called using an object of @code{some_class}.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	977
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	978 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	979 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	980 >> some_class.circumference (3)
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	981 @result{} ans = 18.850
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	982 >> obj = some_class ();
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	983 New instance created.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	984 >> obj.circumference (3)
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	985 @result{} ans = 18.850
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	986 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	987 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	988
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	989 Additionally, class methods can be defined as functions in a folder of the same
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	990 name as the class prepended with the @samp{@@} symbol
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	991 (@pxref{Creating a Class}). The main @code{classdef} file has to be stored in
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	992 this class folder as well.
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	993
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	994 @node Inheritance
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	995 @subsection Inheritance
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	996
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	997 Classes can inherit from other classes. In this case all properties and
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	998 methods of the superclass are inherited to the subclass, considering their
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	999 access rights. Use this syntax to inherit from @code{superclass}:
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1000
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1001 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1002 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1003 classdef subclass < superclass
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1004 @dots{}
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1005 endclassdef
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1006 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1007 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1008
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1009 @node Value Classes vs. Handle Classes
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1010 @subsection Value Classes vs. Handle Classes
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1011
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1012 There are two intrinsically different types of @code{classdef} classes, whose
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1013 major difference is the behavior regarding variable assignment. The first type
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1014 are @b{value classes}:
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1015
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1016 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1017 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1018 classdef value_class
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1019 properties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1020 prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1021 endproperties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1022
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1023 methods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1024 function obj = set_prop1 (obj, val)
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1025 obj.prop1 = val;
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1026 endfunction
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1027 endmethods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1028 endclassdef
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1029 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1030 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1031
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1032 @noindent
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1033 Assigning an object of that class to another variable essentially creates a new
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1034 object:
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1035
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1036 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1037 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1038 >> a = value_class ();
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1039 >> a.prop1 = 1;
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1040 >> b = a;
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1041 >> b.prop1 = 2;
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1042 >> b.prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1043 @result{} ans = 2
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1044 >> a.prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1045 @result{} ans = 1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1046 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1047 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1048
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1049 But that also means that you might have to assign the output of a method that
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1050 changes properties back to the object manually:
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1051
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1052 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1053 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1054 >> a = value_class ();
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1055 >> a.prop1 = 1;
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1056 >> a.set_prop1 (3);
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1057 @result{} ans =
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1058
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1059 <object value_class>
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1060
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1061 >> ans.prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1062 @result{} ans = 3
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1063 >> a.prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1064 @result{} ans = 1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1065 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1066 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1067
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1068 The second type are @b{handle classes}. Those classes have to be derived from
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1069 the abstract @code{handle} class:
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1070
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1071 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1072 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1073 classdef handle_class < handle
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1074 properties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1075 prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1076 endproperties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1077
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1078 methods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1079 function set_prop1 (obj, val)
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1080 obj.prop1 = val;
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1081 endfunction
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1082 endmethods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1083 endclassdef
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1084 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1085 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1086
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1087 In the following example, the variables @code{a} and @code{b} refer to the
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1088 very same object of class @code{handle_class}:
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1089
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1090 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1091 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1092 >> a = handle_class ();
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1093 >> a.prop1 = 1;
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1094 >> b = a;
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1095 >> b.prop1 = 2;
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1096 >> b.prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1097 @result{} ans = 2
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1098 >> a.prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1099 @result{} ans = 2
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1100 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1101 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1102
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1103 Object properties that are modified by a method of an handle class are changed
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1104 persistently:
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1105
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1106 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1107 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1108 >> a.set_prop1 (3);
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1109 >> a.prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1110 @result{} ans = 3
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1111 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1112 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1113

Mercurial > octave

annotate doc/interpreter/oop.txi @ 25024:3c817af70eed stable