octave: doc/interpreter/oop.txi annotate

annotate doc/interpreter/oop.txi @ 31548:c8ad083a5802 stable

maint: Clean up m-files before Octave 8.1 release. * external.txi, oop.txi, Table.h, documentation.cc, gui-preferences-ed.h, lo-specfun.cc, range.tst : Eliminate triple newlines. * Map.m, MemoizedFunction.m, delaunayn.m, inputParser.m, __publish_latex_output__.m, publish.m, unpack.m, fminbnd.m, __add_default_menu__.m, gammainc.m, gallery.m, hadamard.m, weboptions.m: Add newline after keyword "function" or before keyword "endfunction" for readability. * getaudiodata.m, pkg.m : Add semicolon to end of line for error() statement. * movegui.m: Combine mutliple calls to set() into one for performance. * __unimplemented__.m (missing_functions): Remove missing functions that have been implemented. * __vectorize__.m, check_default_input.m, betaincinv.m, gammaincinv.m: Remove semicolon at end of line with "function" declaration. * weboptions.m: Remove semicolon at end of line with "if" keyword. * integrate_adaptive.m, factor.m: Use keyword "endif" rather than bare "end".

author	Rik <rik@octave.org>
date	Fri, 25 Nov 2022 21:23:54 -0800
parents	796f54d4ddbf
children	597f3ee61a48

rev	line source
30564 796f54d4ddbf update Octave Project Developers copyright for the new year John W. Eaton <jwe@octave.org> parents: 28652 diff changeset	1 @c Copyright (C) 2008-2022 The Octave Project Developers
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	2 @c
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	3 @c This file is part of Octave.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	4 @c
24534 194eb4bd202b maint: Update punctuation for GPL v3 license text. Rik <rik@octave.org> parents: 24510 diff changeset	5 @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	6 @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	7 @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	8 @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	9 @c
24358 3516d922b2bf Revert change to Copyright word wrapping in 907f8c3e1c8d. Rik <rik@octave.org> parents: 24357 diff changeset	10 @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	11 @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	12 @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	13 @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	14 @c
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	15 @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	16 @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	17 @c <https://www.gnu.org/licenses/>.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	18
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	19 @c FIXME
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	20 @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	21 @c the example directory without the "@"!!
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	22
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	23 @node Object Oriented Programming
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	24 @chapter Object Oriented Programming
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	25
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	26 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	27 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	28 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	29 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	30 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	31
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	32 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	33 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	34 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	35 for polynomials.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	36
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	37 @menu
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	38 * Creating a Class::
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	39 * Class Methods::
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	40 * Indexing Objects::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	41 * Overloading Objects::
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	42 * 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	43 * classdef Classes::
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	44 @end menu
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	45
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	46 @node Creating a Class
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	47 @section Creating a Class
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	48
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	49 This chapter illustrates user-defined classes and object oriented programming
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	50 through a custom class designed for polynomials. This class was chosen for
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	51 its simplicity which does not distract unnecessarily from the discussion of
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	52 the programming features of Octave. Even so, a bit of background on the goals
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	53 of the polynomial class is necessary before the syntax and techniques of Octave
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	54 object oriented programming are introduced.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	55
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	56 The polynomial class is used to represent polynomials of the form
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	57 @tex
050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	58 $$
050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	59 a_0 + a_1 x + a_2 x^2 + \ldots a_n x^n
050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	60 $$
050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	61 @end tex
050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	62 @ifnottex
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	63
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	64 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	65 a0 + a1 * x + a2 * x^2 + @dots{} + an * x^n
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	66 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	67
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	68 @end ifnottex
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	69 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	70 where
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	71 @tex
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	72 $a_0$, $a_1$, etc. are elements of $\Re$.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	73 @end tex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	74 @ifnottex
21530 7c143e73e921 doc: Don't create end-of-sentence period with "etc." in Texinfo. Rik <rik@octave.org> parents: 21076 diff changeset	75 a0, a1, etc.@: are real scalars.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	76 @end ifnottex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	77 Thus the polynomial can be represented by a vector
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	78
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	79 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	80 a = [a0, a1, a2, @dots{}, an];
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	81 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	82
24510 a2569d574ae5 Add a help entry and documentation for @ character (bug #52771). Daniel J Sebald <daniel.sebald@ieee.org> parents: 24360 diff changeset	83 @opindex @@ class methods
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	84 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	85 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	86 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	87 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	88 @file{@@polynomial} directory.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	89
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	90 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	91 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	92 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	93 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	94
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	95 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	96 @EXAMPLEFILE(@polynomial/polynomial.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	97 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	98
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	99 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	100 @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	101 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	102 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	103
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	104 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	105 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	106 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	107
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	108 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	109 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	110 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	111 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	112 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	113 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	114 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	115 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	116 of a class.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	117
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	118 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	119 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	120 @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	121 @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	122 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	123
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	124 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	125 @code{isa} functions can be used. For example:
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	126
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	127 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	128 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	129 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	130 isobject (p)
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	131 @result{} 1
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	132 isa (p, "polynomial")
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	133 @result{} 1
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	134 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	135 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	136
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	137 @DOCSTRING(isobject)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	138
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	139 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	140 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	141 function.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	142
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	143 @DOCSTRING(methods)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	144
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	145 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	146 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	147 @code{ismethod} function can be used.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	148
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	149 @DOCSTRING(ismethod)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	150
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	151 @noindent
26145 64b972120ec3 doc: Mention example method "roots" in OOP example (bug #55120). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 25054 diff changeset	152 For a polynomial class it makes sense to have a method to compute its roots.
64b972120ec3 doc: Mention example method "roots" in OOP example (bug #55120). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 25054 diff changeset	153
64b972120ec3 doc: Mention example method "roots" in OOP example (bug #55120). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 25054 diff changeset	154 @example
26294 3c5863948bb3 doc: grammarcheck C++ and txi files. Rik <rik@octave.org> parents: 26145 diff changeset	155 @group
26145 64b972120ec3 doc: Mention example method "roots" in OOP example (bug #55120). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 25054 diff changeset	156 @EXAMPLEFILE(@polynomial/roots.m)
26294 3c5863948bb3 doc: grammarcheck C++ and txi files. Rik <rik@octave.org> parents: 26145 diff changeset	157 @end group
26145 64b972120ec3 doc: Mention example method "roots" in OOP example (bug #55120). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 25054 diff changeset	158 @end example
64b972120ec3 doc: Mention example method "roots" in OOP example (bug #55120). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 25054 diff changeset	159
64b972120ec3 doc: Mention example method "roots" in OOP example (bug #55120). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 25054 diff changeset	160 We can check for the existence of the @code{roots}-method by calling:
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	161
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	162 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	163 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	164 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	165 ismethod (p, "roots")
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	166 @result{} 1
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	167 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	168 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	169
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	170 @node Class Methods
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	171 @section Class Methods
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	172
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	173 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	174 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	175 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	176 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	177 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	178 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	179 class which can be confusing.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	180
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	181 @noindent
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	182 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	183
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	184 @example
23371 a5280a05b188 doc: Change example old-style class code to overload disp rather than display. Rik <rik@octave.org> parents: 23220 diff changeset	185 @EXAMPLEFILE(@polynomial/disp.m)
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	186 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	187
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	188 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	189 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	190 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	191 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	192 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	193 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	194 should be retrieved.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	195
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	196 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	197 @EXAMPLEFILE(@polynomial/get.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	198 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	199
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	200 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	201 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	202 any additional arguments should be property/value pairs.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	203
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	204 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	205 @EXAMPLEFILE(@polynomial/set.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	206 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	207
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	208 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	209 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	210 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	211 @code{set} method.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	212
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	213 @example
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	214 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	215 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	216
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	217 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	218 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	219 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	220 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	221
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	222 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	223 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	224 example:
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	225
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	226 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	227 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	228 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	229 save userclass.mat p
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	230 clear p
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	231 load userclass.mat
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	232 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	233 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	234
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	235 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	236 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	237 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	238 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	239 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	240
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	241 @DOCSTRING(saveobj)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	242
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	243 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	244 @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	245 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	246 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	247 object.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	248
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	249 @DOCSTRING(loadobj)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	250
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	251 @node Indexing Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	252 @section Indexing Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	253
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	254 @menu
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	255 * Defining Indexing And Indexed Assignment::
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	256 * Indexed Assignment Optimization::
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	257 @end menu
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	258
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	259 @node Defining Indexing And Indexed Assignment
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	260 @subsection Defining Indexing And Indexed Assignment
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	261
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	262 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	263 @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	264 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	265 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	266 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	267 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	268 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	269 determined by the @code{subsref} method.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	270
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	271 @DOCSTRING(subsref)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	272
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	273 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	274 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	275 @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	276 @code{subsref} method looks like
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	277
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	278 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	279 @EXAMPLEFILE(@polynomial/subsref.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	280 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	281
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 17744 diff changeset	282 The equivalent functionality for subscripted assignments uses the
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	283 @code{subsasgn} method.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	284
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	285 @DOCSTRING(subsasgn)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	286
12534 5b9b2645db26 Add optimize_subsasgn_calls function to documentation. Rik <octave@nomad.inbox5.com> parents: 12448 diff changeset	287 @DOCSTRING(optimize_subsasgn_calls)
5b9b2645db26 Add optimize_subsasgn_calls function to documentation. Rik <octave@nomad.inbox5.com> parents: 12448 diff changeset	288
9285 226f6d001ee2 further improve the polynomial example, fix indexing Jaroslav Hajek <highegg@gmail.com> parents: 9251 diff changeset	289 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	290 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	291 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	292 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	293
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	294 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	295 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	296 @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	297
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	298 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	299 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	300 @EXAMPLEFILE(@polynomial/end.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	301 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	302 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	303
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	304 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	305 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	306 @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	307 class is then
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	308
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	309 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	310 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	311 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	312 p@{end-1@}
14093 050bc580cb60 doc: Various docstring improvements before 3.6.0 release. Rik <octave@nomad.inbox5.com> parents: 12951 diff changeset	313 @result{} 3
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	314 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	315 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	316
21076 b433f9990452 strip trailing whitespace from files John W. Eaton <jwe@octave.org> parents: 21072 diff changeset	317 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	318 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	319
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	320 @DOCSTRING(subsindex)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	321
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	322 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	323
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	324 @DOCSTRING(colon)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	325
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	326 @node Indexed Assignment Optimization
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	327 @subsection Indexed Assignment Optimization
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	328
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	329 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	330 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	331 call to @code{subsasgn}
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	332
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	333 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	334 @group
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	335 ss = substruct ("()", @{1@});
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	336 x = subsasgn (x, ss, 1);
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	337 @end group
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	338 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	339
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	340 @noindent
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	341 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	342
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	343 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	344 @group
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	345 function x = subsasgn (x, ss, val)
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	346 @dots{}
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	347 x.myfield (ss.subs@{1@}) = val;
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	348 endfunction
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	349 @end group
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	350 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	351
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	352 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	353 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	354 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	355 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	356 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	357 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	358 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	359 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	360 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	361 classes that intrinsically store large arrays.
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	362
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	363 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	364 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	365 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	366 @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	367 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	368 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	369 @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	370 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	371 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	372 element takes constant time.
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	373
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	374 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	375 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	376 @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	377 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	378 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	379 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	380 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	381
10846 a4f482e66b65 Grammarcheck more of the documentation. Rik <octave@nomad.inbox5.com> parents: 10791 diff changeset	382 Since this optimization may change the way code works (especially if badly
28652 bb0ca2753bc2 update docs for built-in variables (bug #58988) John W. Eaton <jwe@octave.org> parents: 26769 diff changeset	383 written), a function @code{optimize_subsasgn_calls} is provided to
bb0ca2753bc2 update docs for built-in variables (bug #58988) John W. Eaton <jwe@octave.org> parents: 26769 diff changeset	384 control it. This feature is enabled by default. Another way to avoid
bb0ca2753bc2 update docs for built-in variables (bug #58988) John W. Eaton <jwe@octave.org> parents: 26769 diff changeset	385 the optimization is to declare subsasgn methods with different output
bb0ca2753bc2 update docs for built-in variables (bug #58988) John W. Eaton <jwe@octave.org> parents: 26769 diff changeset	386 and input arguments like this:
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	387
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	388 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	389 @group
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	390 function y = subsasgn (x, ss, val)
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	391 @dots{}
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	392 endfunction
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	393 @end group
9602 dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	394 @end example
dba091e1ee39 document subsasgn optimization in the OOP chapter Jaroslav Hajek <highegg@gmail.com> parents: 9285 diff changeset	395
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	396 @node Overloading Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	397 @section Overloading Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	398
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	399 @menu
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	400 * Function Overloading::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	401 * Operator Overloading::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	402 * Precedence of Objects::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	403 @end menu
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	404
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	405 @node Function Overloading
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	406 @subsection Function Overloading
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	407
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	408 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	409 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	410 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	411
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	412 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	413 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	414 @EXAMPLEFILE(@polynomial/polyval.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	415 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	416 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	417
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	418 This function just hands off the work to the normal Octave @code{polyval}
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	419 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	420 polynomial class is the @code{plot} function.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	421
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	422 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	423 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	424 @EXAMPLEFILE(@polynomial/plot.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	425 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	426 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	427
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	428 @noindent
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	429 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	430 roots of the polynomial.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	431
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	432 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	433 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	434 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	435 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	436 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	437 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	438
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	439 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	440 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	441 @EXAMPLEFILE(@polynomial/double.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	442 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	443 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	444
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	445 @node Operator Overloading
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	446 @subsection Operator Overloading
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	447 @cindex addition
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	448 @cindex and operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	449 @cindex arithmetic operators
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	450 @cindex boolean expressions
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	451 @cindex boolean operators
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	452 @cindex comparison expressions
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	453 @cindex complex-conjugate transpose
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	454 @cindex division
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	455 @cindex equality operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	456 @cindex equality, tests for
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	457 @cindex exponentiation
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	458 @cindex expressions, boolean
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	459 @cindex expressions, comparison
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	460 @cindex expressions, logical
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	461 @cindex greater than operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	462 @cindex Hermitian operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	463 @cindex less than operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	464 @cindex logical expressions
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	465 @cindex logical operators
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	466 @cindex matrix multiplication
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	467 @cindex multiplication
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	468 @cindex negation
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	469 @cindex not operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	470 @cindex operators, arithmetic
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	471 @cindex operators, boolean
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	472 @cindex operators, logical
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	473 @cindex operators, relational
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	474 @cindex or operator
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	475 @cindex quotient
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	476 @cindex relational operators
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	477 @cindex subtraction
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	478 @cindex tests for equality
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	479 @cindex transpose
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	480 @cindex transpose, complex-conjugate
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	481 @cindex unary minus
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	482
15568 38e64d9f0fda doc: Workaround text overlap in pdf documentation caused by bug in Texinfo. Rik <rik@octave.org> parents: 14856 diff changeset	483 @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	484 @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	485 @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	486 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	487 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	488 user class.
38e64d9f0fda doc: Workaround text overlap in pdf documentation caused by bug in Texinfo. Rik <rik@octave.org> parents: 14856 diff changeset	489
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	490 @float Table,tab:overload_ops
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	491 @opindex +
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	492 @opindex -
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	493 @opindex .*
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	494 @opindex *
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	495 @opindex ./
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	496 @opindex /
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	497 @opindex .\
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	498 @opindex \
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	499 @opindex .^
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	500 @opindex ^
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	501 @opindex <
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	502 @opindex <=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	503 @opindex >
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	504 @opindex >=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	505 @opindex ==
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	506 @opindex !=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	507 @opindex ~=
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	508 @opindex &
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	509 @opindex \|
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	510 @opindex !
24550 966c3283a164 doc: Fix appearance of '.' and "'" in Operator Index (bug #52813). Rik <rik@octave.org> parents: 24534 diff changeset	511 @opindex @code{'}
966c3283a164 doc: Fix appearance of '.' and "'" in Operator Index (bug #52813). Rik <rik@octave.org> parents: 24534 diff changeset	512 @opindex @code{.'}
11403 b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	513 @opindex :
b8b08b1ac21f Add missing operator functions to doc/interpreter. Judd Storrs <jstorrs@gmail.com> parents: 11377 diff changeset	514 @opindex <
8286 6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	515
23131 a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	516 @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	517 @headitem Operation @tab Method @tab Description
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{plus (a, b)} @tab Binary addition
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{minus (a, b)} @tab Binary subtraction
a7523328f1f7 * oop.txi: Improve table formatting (bug #50203) John W. Eaton <jwe@octave.org> parents: 23083 diff changeset	520 @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	521 @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	522 @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	523 @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	524 @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	525 @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	526 @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	527 @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	528 @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	529 @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	530 @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	531 @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	532 @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	533 @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	534 @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	535 @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	536 @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	537 @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	538 @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	539 @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	540 @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	541 @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	542 @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	543 @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	544 @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	545 @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	546 @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	547 @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	548 @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	549 @end multitable
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	550 @caption{Available overloaded operators and their corresponding class method}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	551 @end float
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	552
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	553 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	554
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	555 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	556 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	557 @EXAMPLEFILE(@polynomial/mtimes.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	558 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	559 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	560
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	561 @node Precedence of Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	562 @subsection Precedence of Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	563
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	564 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	565 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	566 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	567 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	568 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	569 be used
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	570
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	571 @DOCSTRING(superiorto)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	572
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	573 @DOCSTRING(inferiorto)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	574
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	575 With the polynomial class, consider the case
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	576
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	577 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	578 2 * polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	579 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	580
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	581 @noindent
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	582 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	583 @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	584 @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	585 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	586 to
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	587
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	588 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	589 @EXAMPLEFILE(@polynomial/polynomial_superiorto.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	590 @end example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	591
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	592 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	593 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	594 @qcode{"double"} class is not actually necessary.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	595
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	596 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	597 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	598
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	599 @node Inheritance and Aggregation
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	600 @section Inheritance and Aggregation
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	601
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	602 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	603 both inheritance and aggregation.
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	604
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	605 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	606 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	607 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	608 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	609 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	610 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	611 third argument of the class function.
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	612
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	613 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	614 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	615 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	616
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	617 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	618 @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	619 >> 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	620 >> 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	621 >> 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	622 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	623 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	624
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	625 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	626 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	627 directory @file{@@FIRfilter}.
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	628
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	629 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	630 @EXAMPLEFILE(@FIRfilter/FIRfilter.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	631 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	632
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	633 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	634 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	635 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	636 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	637 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	638 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	639 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	640 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	641 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	642 overwritten.
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	643
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	644 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	645 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	646 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	647 inheritance structure.
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	648
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	649 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	650 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	651 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	652
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	653 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	654 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	655 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	656
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	657 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	658 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	659 @EXAMPLEFILE(@FIRfilter/display.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	660 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	661 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	662
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	663 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	664 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	665 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	666 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	667 @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	668 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	669 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	670 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	671
705361dfe353 doc: disp rather than display should be overloaded (bug #50640, bug #50729). Kai T. Ohlhus <k.ohlhus@gmail.com> parents: 23409 diff changeset	672 @DOCSTRING(display)
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	673
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	674 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	675 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	676 the underlying structure.
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	677
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	678 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	679 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	680 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	681 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	682 octave:2> class (f)
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	683 ans = FIRfilter
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	684 octave:3> isa (f, "FIRfilter")
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	685 ans = 1
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	686 octave:4> isa (f, "polynomial")
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	687 ans = 1
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	688 octave:5> struct (f)
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 17744 diff changeset	689 ans =
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	690
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	691 scalar structure containing the fields:
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	692
a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	693 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	694 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	695 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	696
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	697 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	698 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	699 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	700 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	701 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	702
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	703 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	704 @EXAMPLEFILE(@FIRfilter/subsref.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	705 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	706
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 15997 diff changeset	707 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	708 to the constructor.
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	709
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	710 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	711 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	712 octave: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	713 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	714 octave:4> y = f(x)
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	715 y =
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	716
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	717 0.33333
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	718 0.66667
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	719 1.00000
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	720 1.00000
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	721 1.00000
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	722 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	723 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	724
17281 bc924baa2c4e doc: Add new @qcode macro for code samples which are quoted. Rik <rik@octave.org> parents: 15997 diff changeset	725 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	726
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	727 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	728 @group
14856 c3fd61c59e9c maint: Use Octave coding conventions for cuddling parentheses in doc directory Rik <octave@nomad.inbox5.com> parents: 14846 diff changeset	729 octave:1> f = FIRfilter (polynomial ([1 1 1]/3));
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	730 octave:2> f.polynomial
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	731 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	732 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	733 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	734
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	735 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	736 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	737 writable
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	738
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	739 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	740 @group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	741 @EXAMPLEFILE(@FIRfilter/subsasgn.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	742 @end group
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	743 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	744
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	745 @noindent
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	746 so that
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	747
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	748 @example
9758 09da0bd91412 Periodic grammar check of Octave documentation files to ensure common format Rik <rdrider0-list@yahoo.com> parents: 9752 diff changeset	749 @group
21061 220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	750 octave:1> f = FIRfilter ();
220506787b93 doc: Overhaul chapter on old-style Object Oriented Programming. Rik <rik@octave.org> parents: 19697 diff changeset	751 octave:2> f.polynomial = polynomial ([1 2 3])
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	752 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	753 @end group
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	754 @end example
f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	755
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	756 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	757 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	758 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	759 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	760 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	761 the aggregation case might be
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	762
9906 8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	763 @example
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	764 @EXAMPLEFILE(@FIRfilter/FIRfilter_aggregation.m)
8d20fb66a0dc more automake fixes John W. Eaton <jwe@octave.org> parents: 9758 diff changeset	765 @end example
9251 f8b8ab529913 improve OOP documentation Robert T. Short <octave@phaselockedsystems.com> parents: 9245 diff changeset	766
21072 a9ed4104ecfd doc: Rewrite documentation for Object Oriented Programming. Rik <rik@octave.org> parents: 21061 diff changeset	767 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	768 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	769
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	770 @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	771 @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	772
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	773 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	774 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	775 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	776 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	777
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	778 @itemize @bullet
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	779 @item
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	780 @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	781
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	782 @item
24359 1da659b26bec doc: grammarcheck of Object Oriented Programming chapter in manual. Rik <rik@octave.org> parents: 24358 diff changeset	783 @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	784
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	785 @item
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	786 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	787 @end itemize
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	788
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	789 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	790 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	791 @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	792
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	793 @menu
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	794 * 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	795 * Properties::
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	796 * Methods::
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	797 * Inheritance::
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	798 * 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	799 @end menu
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	800
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	801 @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	802 @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	803
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	804 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	805 (@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	806
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	807 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	808 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	809 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	810 properties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	811 endproperties
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 methods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	814 endmethods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	815 endclassdef
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	816 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	817 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	818
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	819 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	820 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	821 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	822 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	823
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	824 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	825 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	826
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	827 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	828 @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	829 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	830
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	831 @noindent
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	832 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	833 constructor:
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	834
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	835 @example
24359 1da659b26bec doc: grammarcheck of Object Oriented Programming chapter in manual. Rik <rik@octave.org> parents: 24358 diff changeset	836 @group
24357 49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	837 >> 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	838 @result{} p =
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	839
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	840 1 + X ^ 2
24359 1da659b26bec doc: grammarcheck of Object Oriented Programming chapter in manual. Rik <rik@octave.org> parents: 24358 diff changeset	841 @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	842 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	843
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	844 @node Properties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	845 @subsection Properties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	846
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	847 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	848 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	849 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	850
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	851 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	852 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	853
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	854 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	855 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	856 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	857 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	858 @var{prop1}
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	859 endproperties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	860
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	861 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	862 @var{prop2}
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	863 endproperties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	864
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	865 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	866 @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	867 endproperties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	868
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	869 properties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	870 @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	871 endproperties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	872 endclassdef
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	873 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	874 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	875
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	876 @noindent
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	877 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	878
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	879 @table @code
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	880 @item public
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	881 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	882
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	883 @item private
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	884 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	885 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	886
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	887 @item protected
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	888 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	889 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	890 @end table
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 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	893 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	894 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	895 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	896 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	897
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	898 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	899 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	900
26769 2f847e3e8d6b split classdef into multiple smaller source files John W. Eaton <jwe@octave.org> parents: 26376 diff changeset	901 @DOCSTRING(properties)
2f847e3e8d6b split classdef into multiple smaller source files John W. Eaton <jwe@octave.org> parents: 26376 diff changeset	902
24357 49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	903 @node Methods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	904 @subsection Methods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	905
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	906 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	907 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	908 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	909 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	910 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	911
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	912 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	913 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	914 methods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	915 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	916 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	917 endfunction
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	918
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	919 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	920 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	921 endfunction
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	922 endmethods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	923
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	924 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	925 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	926 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	927 endfunction
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	928 endmethods
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 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	931 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	932 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	933 endfunction
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	934 endmethods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	935 endclassdef
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	936 @end example
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 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	939 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	940 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	941
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	942 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	943 @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	944 @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	945
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	946 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	947 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	948 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	949 ("@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	950
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	951 @example
24359 1da659b26bec doc: grammarcheck of Object Oriented Programming chapter in manual. Rik <rik@octave.org> parents: 24358 diff changeset	952 @group
24357 49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	953 >> 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	954 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	955 >> 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	956 >> obj.disp (); # equal
24359 1da659b26bec doc: grammarcheck of Object Oriented Programming chapter in manual. Rik <rik@octave.org> parents: 24358 diff changeset	957 @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	958 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	959
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	960 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	961 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	962
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	963 @table @code
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	964 @item public
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	965 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	966
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	967 @item private
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	968 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	969 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	970
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	971 @item protected
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	972 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	973 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	974 @end table
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	975
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	976 @noindent
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	977 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	978
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	979 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	980 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	981 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	982 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	983 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	984 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	985
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	986 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	987 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	988 >> 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	989 @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	990 >> 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	991 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	992 >> 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	993 @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	994 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	995 @end example
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 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	998 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	999 (@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	1000 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	1001
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1002 @node Inheritance
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1003 @subsection Inheritance
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1004
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1005 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	1006 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	1007 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	1008
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1009 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1010 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1011 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	1012 @dots{}
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1013 endclassdef
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1014 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1015 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1016
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1017 @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	1018 @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	1019
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1020 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	1021 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	1022 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	1023
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1024 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1025 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1026 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	1027 properties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1028 prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1029 endproperties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1030
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1031 methods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1032 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	1033 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	1034 endfunction
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1035 endmethods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1036 endclassdef
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1037 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1038 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1039
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1040 @noindent
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1041 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	1042 object:
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1043
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1044 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1045 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1046 >> 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	1047 >> 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	1048 >> b = a;
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1049 >> 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	1050 >> b.prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1051 @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	1052 >> a.prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1053 @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	1054 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1055 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1056
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1057 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	1058 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	1059
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1060 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1061 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1062 >> 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	1063 >> 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	1064 >> 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	1065 @result{} ans =
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1066
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1067 <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	1068
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1069 >> ans.prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1070 @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	1071 >> a.prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1072 @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	1073 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1074 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1075
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1076 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	1077 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	1078
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1079 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1080 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1081 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	1082 properties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1083 prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1084 endproperties
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1085
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1086 methods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1087 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	1088 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	1089 endfunction
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1090 endmethods
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1091 endclassdef
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1092 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1093 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1094
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1095 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	1096 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	1097
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1098 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1099 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1100 >> 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	1101 >> 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	1102 >> b = a;
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1103 >> 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	1104 >> b.prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1105 @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	1106 >> a.prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1107 @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	1108 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1109 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1110
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1111 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	1112 persistently:
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1113
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1114 @example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1115 @group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1116 >> 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	1117 >> a.prop1
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1118 @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	1119 @end group
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1120 @end example
49fc0178028c doc: new section about classdef classes with example (bug #44590). Markus Mützel <markus.muetzel@gmx.de> parents: 23219 diff changeset	1121

Mercurial > octave

annotate doc/interpreter/oop.txi @ 31548:c8ad083a5802 stable