octave-nkf: doc/interpreter/oop.txi annotate

annotate doc/interpreter/oop.txi @ 9073:17ce09c3d030

Cleanup oop.texi

author	Rik <rdrider0-list@yahoo.com>
date	Wed, 01 Apr 2009 17:21:07 -0700
parents	fa78cb8d8a5c
children	923c7cb7f13f

rev	line source
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	1 @c Copyright (C) 2008 David Bateman
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
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	5 @c Octave is free software; you can redistribute it and/or modify it
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	6 @c under the terms of the GNU General Public License as published by the
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	7 @c Free Software Foundation; either version 3 of the License, or (at
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	8 @c your option) any later version.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	9 @c
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	10 @c Octave is distributed in the hope that it will be useful, but WITHOUT
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	11 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	12 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	13 @c for more details.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	14 @c
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
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	17 @c <http://www.gnu.org/licenses/>.
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 @macro classfile{class, file}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	24 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	25 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	26 @verbatiminclude @value{abs_top_srcdir}/examples/\class\/\file\
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	27 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	28 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	29 @end macro
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	30
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	31 @macro polynomialfile{file}
8256 dba0037e6602 Import new texinfo.tex allowing @ in directory name. Update OOP example class location David Bateman <dbateman@free.fr> parents: 8235 diff changeset	32 @classfile{@@polynomial,\file\}
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	33 @end macro
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	34
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	35 @node Object Oriented Programming
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	36 @chapter Object Oriented Programming
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	37
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	38 Octave includes the capability to include user classes, including the
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	39 features of operator and function overloading. Equally a user class
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	40 can be used to encapsulate certain properties of the class so that
8347 fa78cb8d8a5c corrections for typos Brian Gough<bjg@network-theory.co.uk> parents: 8295 diff changeset	41 they cannot be altered accidentally and can be set up to address the
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	42 issue of class precedence in mixed class operations.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	43
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	44 This chapter discussions the means of constructing a user class with
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	45 the example of a polynomial class, how to query and set the properties
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	46 of this class, together with the means to overload operators and
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	47 functions.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	48
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	49 @menu
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	50 * Creating a Class::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	51 * Manipulating Classes::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	52 * Indexing Objects::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	53 * Overloading Objects::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	54 @end menu
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 @node Creating a Class
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	57 @section Creating a Class
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	58
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	59 We use in the following text a polynomial class to demonstrate the use
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	60 of object oriented programming within Octave. This class was chosen as
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	61 it is simple, and so doesn't distract unnecessarily from the
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	62 discussion of the programming features of Octave. However, even still
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	63 a small understand of the polynomial class itself is necessary to
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	64 fully grasp the techniques described.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	65
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	66 The polynomial class is used to represent polynomials of the form
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	67
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	68 @example
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	69 @group
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	70 @iftex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	71 @tex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	72 $a_0 + a_1 x + a_2 x^2 + \ldots a_n x^n$
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	73 @end tex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	74 @end iftex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	75 @ifnottex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	76 a0 + a1 * x + a2 * x^2 + @dots{} + an * x^n
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	77 @end ifnottex
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	78 @end group
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	79 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	80
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	81 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	82 where
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	83 @iftex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	84 @tex
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	85 $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	86 @end tex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	87 @end iftex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	88 @ifnottex
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	89 a0, a1, etc. are real scalars.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	90 @end ifnottex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	91 Thus the polynomial can be represented by a vector
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	92
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	93 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	94 a = [a0, a1, a2, @dots{}, an];
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	95 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	96
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	97 We therefore now have sufficient information about the requirements of
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	98 the class constructor for our polynomial class to write it. All object
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	99 oriented classes in Octave, must be contained with a directory taking
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	100 the name of the class, prepended with the @@ symbol. For example, with
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	101 our polynomial class, we would place the methods defining the class in
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	102 the @@polynomial directory.
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 The constructor of the class, must have the name of the class itself
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	105 and so in our example the constructor with have the name
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	106 @file{@@polynomial/polynomial.m}. Also ideally when the constructor is
17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	107 called with no arguments to should return a value object. So for example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	108 our polynomial might look like
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	109
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	110 @polynomialfile{polynomial.m}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	111
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	112 Note that the return value of the constructor must be the output of
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	113 the @code{class} function called with the first argument being a
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	114 structure and the second argument being the class name. An example of
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	115 the call to this constructor function is then
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	116
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	117 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	118 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	119 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	120
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	121 Note that methods of a class can be documented. The help for the
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	122 constructor itself can be obtained with the constructor name, that is
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	123 for the polynomial constructor @code{help polynomial} will return the
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	124 help string. Also the help can be obtained by restricting the search
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	125 for the help to a particular class, for example @code{help
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	126 @@polynomial/polynomial}. This second method is the only means of
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	127 getting help for the overloaded methods and functions of the class.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	128
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	129 The same is true for other Octave functions that take a function name
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	130 as an argument. For example @code{type @@polynomial/display} will
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	131 print the code of the display method of the polynomial class to the
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	132 screen, and @code{dbstop @@polynomial/display} will set a breakpoint
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	133 at the first executable line of the display method of the polynomial
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	134 class.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	135
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	136 To check where a variable is a user class, the @code{isobject} and
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	137 @code{isa} functions can be used. for example
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 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	140 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	141 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	142 isobject (p)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	143 @result{} 1
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	144 isa (p, "polynomial")
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	145 @result{} 1
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	146 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	147 @end example
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(isobject)
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
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	152 The available methods of a class can be displayed with the
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	153 @code{methods} function.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	154
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	155 @DOCSTRING(methods)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	156
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	157 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	158 To enquiry whether a particular method is available to a user class, the
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	159 @code{ismethod} function can be used.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	160
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	161 @DOCSTRING(ismethod)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	162
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	163 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	164 For example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	165
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	166 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	167 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	168 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	169 ismethod (p, "roots")
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	170 @result{} 1
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	171 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	172 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	173
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	174 @node Manipulating Classes
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	175 @section Manipulating Classes
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	176
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	177 There are a number of basic classes methods that can be defined to allow
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	178 the contents of the classes to be queried and set. The most basic of
17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	179 these is the @code{display} method. The @code{display} method is used
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	180 by Octave when displaying a class on the screen, due to an expression
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	181 that is not terminated with a semicolon. If this method is not defined,
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	182 then Octave will printed nothing when displaying the contents of a class.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	183
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	184 @DOCSTRING(display)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	185
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	186 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	187 An example of a display method for the polynomial class might be
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	188
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	189 @polynomialfile{display.m}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	190
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	191 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	192 Note that in the display method, it makes sense to start the method
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	193 with the line @code{fprintf("%s =", inputname(1))} to be consistent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	194 with the rest of Octave and print the variable name to be displayed
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	195 when displaying the class.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	196
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	197 To be consistent with the Octave graphic handle classes, a class
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	198 should also define the @code{get} and @code{set} methods. The
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	199 @code{get} method should accept one or two arguments, and given one
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	200 argument of the appropriate class it should return a structure with
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	201 all of the properties of the class. For example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	202
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	203 @polynomialfile{get.m}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	204
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	205 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	206 Similarly, the @code{set} method should taken as its first argument an
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	207 object to modify, and then take property/value pairs to be modified.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	208
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	209 @polynomialfile{set.m}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	210
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	211 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	212 Note that as Octave does not implement pass by reference, than the
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	213 modified object is the return value of the @code{set} method and it
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	214 must be called like
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	215
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	216 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	217 p = set (p, "a", [1, 0, 0, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	218 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	219
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	220 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	221 Also the @code{set} method makes use of the @code{subsasgn} method of
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	222 the class, and this method must be defined. The @code{subsasgn} method
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	223 is discussed in the next section.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	224
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	225 Finally, user classes can be considered as a special type of a
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	226 structure, and so they can be saved to a file in the same manner as a
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	227 structure. For example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	228
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	229 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	230 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	231 p = polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	232 save userclass.mat p
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	233 clear p
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	234 load userclass.mat
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	235 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	236 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	237
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	238 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	239 All of the file formats supported by @code{save} and @code{load} are
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	240 supported. In certain circumstances, a user class might either contain
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	241 a field that it makes no sense to save or a field that needs to be
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	242 initialized before it is saved. This can be done with the
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	243 @code{saveobj} method of the class
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	244
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	245 @DOCSTRING(saveobj)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	246
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	247 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	248 @code{saveobj} is called just prior to saving the class to a
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	249 file. Likely, the @code{loadobj} method is called just after a class
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	250 is loaded from a file, and can be used to ensure that any removed
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	251 fields are reinserted into the user object.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	252
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	253 @DOCSTRING(loadobj)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	254
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	255 @node Indexing Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	256 @section Indexing Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	257
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	258 Objects in can be indexed with parentheses, either like
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	259 @code{@var{a} (@var{idx})} or like @code{@var{a} @{@var{idx}@}}, or even
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	260 like @code{@var{a} (@var{idx}).@var{field}}. However, it is up to the user
17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	261 to decide what this indexing actually means. In the case of our polynomial
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	262 class @code{@var{p} (@var{n})} might mean either the coefficient of the
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	263 @var{n}-th power of the polynomial, or it might be the evaluation of the
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	264 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	265 determined by the @code{subsref} method.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	266
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	267 @DOCSTRING(subsref)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	268
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	269 For example we might decide that indexing with "()" evaluates the
8235 7eedf503ba1c Small makeinfo doc fixes David Bateman <dbateman@free.fr> parents: 8223 diff changeset	270 polynomial and indexing with "@{@}" returns the @var{n}-th coefficient.
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	271 In this case the @code{subsref} method of our polynomial class might look like
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	272
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	273 @polynomialfile{subsref.m}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	274
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	275 The equivalent functionality for subscripted assignments uses the
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	276 @code{subsasgn} method.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	277
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	278 @DOCSTRING(subsasgn)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	279
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	280 If you wish to use the @code{end} keyword in subscripted expressions
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	281 of an object. Then the user needs to define the @code{end} method for
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	282 the class.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	283
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	284 @DOCSTRING(end)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	285
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	286 For example the @code{end} method for our polynomial class might look like
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	287
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	288 @polynomialfile{end.m}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	289
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	290 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	291 which is a fairly generic @code{end} method that has a behavior similar to
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	292 the @code{end} keyword for Octave Array classes. It can then be used for
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	293 example like
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	294
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	295 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	296 @group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	297 p = polynomial([1,2,3,4]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	298 p(end-1)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	299 @result{} 3
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	300 @end group
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	301 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	302
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	303 Objects can also be used as the index in a subscripted expression themselves
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	304 and this is controlled with the @code{subsindex} function.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	305
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	306 @DOCSTRING(subsindex)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	307
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	308 Finally, objects can equally be used like ranges, using the @code{colon}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	309 method
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	310
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	311 @DOCSTRING(colon)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	312
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	313 @node Overloading Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	314 @section Overloading Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	315
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	316 @menu
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	317 * Function Overloading::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	318 * Operator Overloading::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	319 * Precedence of Objects::
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	320 @end menu
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	321
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	322 @node Function Overloading
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	323 @subsection Function Overloading
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	324
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	325 Any Octave function can be overloaded, and allows a object specific
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	326 version of this function to be called as needed. A pertinent example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	327 for our polynomial class might be to overload the @code{polyval} function
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	328 like
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	329
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	330 @polynomialfile{polyval.m}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	331
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	332 This function just hands off the work to the normal Octave @code{polyval}
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	333 function. Another interesting example for an overloaded function for our
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	334 polynomial class is the @code{plot} function.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	335
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	336 @polynomialfile{plot.m}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	337
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	338 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	339 which allows polynomials to be plotted in the domain near the region
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	340 of the roots of the polynomial.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	341
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	342 Functions that are of particular interest to be overloaded are the class
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	343 conversion functions such as @code{double}. Overloading these functions
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	344 allows the @code{cast} function to work with the user class and can aid
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	345 in the use of methods of other classes with the user class. An example
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	346 @code{double} function for our polynomial class might look like.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	347
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	348 @polynomialfile{double.m}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	349
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	350 @node Operator Overloading
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	351 @subsection Operator Overloading
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	352
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	353 @float Table,tab:overload_ops
8286 6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	354
6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	355 @anchor{doc-rdivide} @anchor{doc-plus} @anchor{doc-minus} @anchor{doc-uminus}
6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	356 @anchor{doc-uplus} @anchor{doc-times} @anchor{doc-mtimes} @anchor{doc-mrdivide}
6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	357 @anchor{doc-ldivide} @anchor{doc-mldivide} @anchor{doc-power}
6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	358 @anchor{doc-mpower} @anchor{doc-lt} @anchor{doc-le} @anchor{doc-gt}
6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	359 @anchor{doc-ge} @anchor{doc-eq} @anchor{doc-ne} @anchor{doc-and}
6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	360 @anchor{doc-or} @anchor{doc-not} @anchor{doc-ctranspose} @anchor{doc-transpose}
6f2d95255911 fix @seealso references to point to existing anchors Thorsten Meyer <thorsten.meyier@gmx.de> parents: 8256 diff changeset	361
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	362 @iftex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	363 @tex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	364 \vskip 6pt
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	365 {\hbox to \hsize {\hfill\vbox{\offinterlineskip \tabskip=0pt
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	366 \halign{
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	367 \vrule height2.0ex depth1.ex width 0.6pt #\tabskip=0.3em &
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	368 # \hfil & \vrule # & # \hfil & \vrule # & # \hfil & # \vrule
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	369 width 0.6pt \tabskip=0pt\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	370 \noalign{\hrule height 0.6pt}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	371 & Operation && Method && Description &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	372 \noalign{\hrule}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	373 & $a + b$ && plus (a, b) && Binary addition operator&\cr
8295 16819ca24fa5 fix typo in docs John W. Eaton <jwe@octave.org> parents: 8286 diff changeset	374 & $a - b$ && minus (a, b) && Binary subtraction operator&\cr
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	375 & $+ a$ && uplus (a) && Unary addition operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	376 & $- a$ && uminus (a) && Unary subtraction operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	377 & $a .* b$ && times (a, b) && Element-wise multiplication operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	378 & $a * b$ && mtimes (a, b) && Matrix multiplication operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	379 & $a ./ b$ && rdivide (a, b) && Element-wise right division operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	380 & $a / b$ && mrdivide (a, b) && Matrix right division operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	381 & $a .\backslash b$ && ldivide (a, b) && Element-wise left division operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	382 & $a \backslash b$ && mldivide (a, b) && Matrix left division operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	383 & $a .\hat b$ && power (a, b) && Element-wise power operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	384 & $a \hat b$ && mpower (a, b) && Matrix power operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	385 & $a < b$ && lt (a, b) && Less than operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	386 & $a <= b$ && le (a, b) && Less than or equal to operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	387 & $a > b$ && gt (a, b) && Greater than operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	388 & $a >= b$ && ge (a, b) && Greater than or equal to operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	389 & $a == b$ && eq (a, b) && Equal to operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	390 & $a != b$ && ne (a, b) && Not equal to operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	391 & $a \& b$ && and (a, b) && Logical and operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	392 & $a \| b$ && or (a, b) && Logical or operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	393 & $! b$ && not (a) && Logical not operator&\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	394 & $a'$ && ctranspose (a) && Complex conjugate transpose operator &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	395 & $a.'$ && transpose (a) && Transpose operator &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	396 & $a : b$ && colon (a, b) && Two element range operator &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	397 & $a : b : c$ && colon (a, b, c) && Three element range operator &\cr
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	398 & $[a, b]$ && horzcat (a, b) && Horizontal concatenation operator &\cr
17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	399 & $[a; b]$ && vertcat (a, b) && Vertical concatenation operator &\cr
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	400 & $a(s_1, \ldots, s_n)$ && subsref (a, s) && Subscripted reference &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	401 & $a(s_1, \ldots, s_n) = b$ && subsasgn (a, s, b) && Subscripted assignment &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	402 & $b (a)$ && subsindex (a) && Convert to zero-based index &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	403 & {\it display} && display (a) && Commandline display function &\cr
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	404 \noalign{\hrule height 0.6pt}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	405 }}\hfill}}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	406 @end tex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	407 @end iftex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	408 @ifnottex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	409 @multitable @columnfractions .1 .20 .20 .40 .1
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	410 @item @tab Operation @tab Method @tab Description @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	411 @item @tab a + b @tab plus (a, b) @tab Binary addition @tab
8295 16819ca24fa5 fix typo in docs John W. Eaton <jwe@octave.org> parents: 8286 diff changeset	412 @item @tab a - b$ @tab minus (a, b) @tab Binary subtraction operator @tab
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	413 @item @tab + a$ @tab uplus (a) @tab Unary addition operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	414 @item @tab - a$ @tab uminus (a) @tab Unary subtraction operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	415 @item @tab a .* b$ @tab times (a, b) @tab Element-wise multiplication operator @tab
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	416 @item @tab a * b$ @tab mtimes (a, b) @tab Matrix multiplication operator @tab
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	417 @item @tab a ./ b$ @tab rdivide (a, b) @tab Element-wise right division operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	418 @item @tab a / b$ @tab mrdivide (a, b) @tab Matrix right division operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	419 @item @tab a .\ b$ @tab ldivide (a, b) @tab Element-wise left division operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	420 @item @tab a \ b$ @tab mldivide (a, b) @tab Matrix left division operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	421 @item @tab a .^ b$ @tab ldivide (a, b) @tab Element-wise power operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	422 @item @tab a ^ b$ @tab mldivide (a, b) @tab Matrix power operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	423 @item @tab a < b$ @tab lt (a, b) @tab Less than operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	424 @item @tab a <= b$ @tab le (a, b) @tab Less than or equal to operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	425 @item @tab a > b$ @tab gt (a, b) @tab Greater than operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	426 @item @tab a >= b$ @tab ge (a, b) @tab Greater than or equal to operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	427 @item @tab a == b$ @tab eq (a, b) @tab Equal to operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	428 @item @tab a != b$ @tab ne (a, b) @tab Not equal to operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	429 @item @tab a \& b$ @tab and (a, b) @tab Logical and operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	430 @item @tab a \| b$ @tab or (a, b) @tab Logical or operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	431 @item @tab ! b$ @tab not (a) @tab Logical not operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	432 @item @tab a'$ @tab ctranspose (a) @tab Complex conjugate transpose operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	433 @item @tab a.'$ @tab transpose (a) @tab Transpose operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	434 @item @tab a : b$ @tab colon (a, b) @tab Two element range operator @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	435 @item @tab a : b : c$ @tab colon (a, b, c) @tab Three element range operator @tab
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	436 @item @tab [a, b]$ @tab horzcat (a, b) @tab Horizontal concatenation operator @tab
17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	437 @item @tab [a; b]$ @tab vertcat (a, b) @tab Vertical concatenation operator @tab
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	438 @item @tab a(s_1, \ldots, s_n)$ @tab subsref (a, s) @tab Subscripted reference @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	439 @item @tab a(s_1, \ldots, s_n) = b$ @tab subsasgn (a, s, b) @tab Subscripted assignment @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	440 @item @tab b (a)$ @tab subsindex (a) @tab Convert to zero-based index @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	441 @item @tab @dfn{display} @tab display (a) @tab Commandline display function @tab
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	442 @end multitable
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	443 @end ifnottex
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	444 @caption{Available overloaded operators and their corresponding class method}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	445 @end float
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	446
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	447 An example @code{mtimes} method for our polynomial class might look like
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	448
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	449 @polynomialfile{mtimes.m}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	450
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	451 @node Precedence of Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	452 @subsection Precedence of Objects
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	453
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	454 Many functions and operators take two or more arguments and so the
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	455 case can easily arise that these functions are called with objects of
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	456 different classes. It is therefore necessary to determine the precedence
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	457 of which method of which class to call when there are mixed objects given
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	458 to a function or operator. To do this the @code{superiorto} and
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	459 @code{inferiorto} functions can be used
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	460
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	461 @DOCSTRING(superiorto)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	462
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	463 @DOCSTRING(inferiorto)
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	464
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	465 For example with our polynomial class consider the case
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	466
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	467 @example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	468 2 * polynomial ([1, 0, 1]);
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	469 @end example
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	470
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	471 @noindent
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	472 That mixes an object of the class "double" with an object of the class
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	473 "polynomial". In this case we like to ensure that the return type of
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	474 the above is of the type "polynomial" and so we use the
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	475 @code{superiorto} function in the class constructor. In particular our
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	476 polynomial class constructor would be modified to be
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	477
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	478 @polynomialfile{polynomial_superiorto.m}
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	479
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	480 Note that user classes always have higher precedence than built-in
9073 17ce09c3d030 Cleanup oop.texi Rik <rdrider0-list@yahoo.com> parents: 8347 diff changeset	481 Octave types. So in fact marking our polynomial class higher than the
8223 0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	482 "double" class is in fact not necessary.
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	483
0c91b9a17dcf Commit missing files from previous change David Bateman <dbateman@free.fr> parents: diff changeset	484

Mercurial > octave-nkf

annotate doc/interpreter/oop.txi @ 9073:17ce09c3d030