Mercurial > octave-nkf
annotate doc/interpreter/oop.txi @ 17281:bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Macro handles options ("on") or properties ("position") more elegantly
than @code{"text"}.
* doc/interpreter/macros.texi: Add new @qcode macro.
* doc/interpreter/tips.txi: Add documentation about @qcode macro.
* doc/interpreter/basics.txi, doc/interpreter/container.txi,
doc/interpreter/emacs.txi, doc/interpreter/errors.txi,
doc/interpreter/eval.txi, doc/interpreter/expr.txi,
doc/interpreter/external.txi, doc/interpreter/func.txi,
doc/interpreter/grammar.txi, doc/interpreter/image.txi,
doc/interpreter/install.txi, doc/interpreter/interp.txi,
doc/interpreter/io.txi, doc/interpreter/matrix.txi,
doc/interpreter/numbers.txi, doc/interpreter/oop.txi,
doc/interpreter/package.txi, doc/interpreter/plot.txi,
doc/interpreter/quad.txi, doc/interpreter/sparse.txi,
doc/interpreter/strings.txi, doc/interpreter/system.txi,
doc/interpreter/vectorize.txi, libinterp/corefcn/balance.cc,
libinterp/corefcn/bitfcns.cc, libinterp/corefcn/cellfun.cc,
libinterp/corefcn/conv2.cc, libinterp/corefcn/data.cc,
libinterp/corefcn/debug.cc, libinterp/corefcn/defaults.cc,
libinterp/corefcn/dirfns.cc, libinterp/corefcn/dlmread.cc,
libinterp/corefcn/error.cc, libinterp/corefcn/file-io.cc,
libinterp/corefcn/find.cc, libinterp/corefcn/gammainc.cc,
libinterp/corefcn/graphics.cc, libinterp/corefcn/help.cc,
libinterp/corefcn/hex2num.cc, libinterp/corefcn/input.cc,
libinterp/corefcn/load-path.cc, libinterp/corefcn/load-save.cc,
libinterp/corefcn/ls-oct-ascii.cc, libinterp/corefcn/lu.cc,
libinterp/corefcn/luinc.cc, libinterp/corefcn/matrix_type.cc,
libinterp/corefcn/oct-hist.cc, libinterp/corefcn/pager.cc,
libinterp/corefcn/pr-output.cc, libinterp/corefcn/pt-jit.cc,
libinterp/corefcn/qz.cc, libinterp/corefcn/rand.cc,
libinterp/corefcn/regexp.cc, libinterp/corefcn/schur.cc,
libinterp/corefcn/sighandlers.cc, libinterp/corefcn/sparse.cc,
libinterp/corefcn/spparms.cc, libinterp/corefcn/str2double.cc,
libinterp/corefcn/svd.cc, libinterp/corefcn/symtab.cc,
libinterp/corefcn/syscalls.cc, libinterp/corefcn/toplev.cc,
libinterp/corefcn/tril.cc, libinterp/corefcn/typecast.cc,
libinterp/corefcn/utils.cc, libinterp/corefcn/variables.cc,
libinterp/dldfcn/__init_fltk__.cc, libinterp/dldfcn/chol.cc,
libinterp/dldfcn/colamd.cc, libinterp/dldfcn/fftw.cc, libinterp/dldfcn/qr.cc,
libinterp/dldfcn/symbfact.cc, libinterp/octave-value/ov-base.cc,
libinterp/octave-value/ov-fcn-handle.cc,
libinterp/octave-value/ov-fcn-inline.cc, libinterp/octave-value/ov-java.cc,
libinterp/octave-value/ov-range.cc, libinterp/octave-value/ov-struct.cc,
libinterp/octave-value/ov-usr-fcn.cc, libinterp/parse-tree/oct-parse.in.yy,
libinterp/parse-tree/pt-binop.cc, libinterp/parse-tree/pt-eval.cc,
libinterp/parse-tree/pt-mat.cc, scripts/@ftp/ftp.m,
scripts/deprecated/java_convert_matrix.m, scripts/deprecated/java_debug.m,
scripts/deprecated/java_unsigned_conversion.m, scripts/deprecated/shell_cmd.m,
scripts/general/dblquad.m, scripts/general/display.m,
scripts/general/genvarname.m, scripts/general/idivide.m,
scripts/general/interp1.m, scripts/general/interp2.m,
scripts/general/interp3.m, scripts/general/interpn.m, scripts/general/isa.m,
scripts/general/profexplore.m, scripts/general/profile.m,
scripts/general/quadgk.m, scripts/general/randi.m, scripts/general/structfun.m,
scripts/general/subsindex.m, scripts/general/triplequad.m,
scripts/geometry/griddata.m, scripts/geometry/griddata3.m,
scripts/geometry/griddatan.m, scripts/geometry/voronoi.m, scripts/help/help.m,
scripts/help/lookfor.m, scripts/image/cmpermute.m, scripts/image/colormap.m,
scripts/image/image.m, scripts/image/imagesc.m, scripts/image/imfinfo.m,
scripts/image/imformats.m, scripts/image/imread.m, scripts/image/imshow.m,
scripts/image/imwrite.m, scripts/image/ind2gray.m, scripts/image/lines.m,
scripts/image/rgb2ind.m, scripts/image/spinmap.m, scripts/io/dlmwrite.m,
scripts/io/strread.m, scripts/io/textread.m, scripts/io/textscan.m,
scripts/java/javaclasspath.m, scripts/java/usejava.m,
scripts/miscellaneous/bzip2.m, scripts/miscellaneous/computer.m,
scripts/miscellaneous/copyfile.m, scripts/miscellaneous/debug.m,
scripts/miscellaneous/dos.m, scripts/miscellaneous/edit.m,
scripts/miscellaneous/gzip.m, scripts/miscellaneous/license.m,
scripts/miscellaneous/mkoctfile.m, scripts/miscellaneous/movefile.m,
scripts/miscellaneous/parseparams.m, scripts/miscellaneous/unix.m,
scripts/optimization/fminbnd.m, scripts/optimization/fminsearch.m,
scripts/optimization/fminunc.m, scripts/optimization/fsolve.m,
scripts/optimization/fzero.m, scripts/optimization/glpk.m,
scripts/optimization/lsqnonneg.m, scripts/optimization/optimset.m,
scripts/optimization/pqpnonneg.m, scripts/pkg/pkg.m, scripts/plot/allchild.m,
scripts/plot/ancestor.m, scripts/plot/area.m, scripts/plot/axis.m,
scripts/plot/bar.m, scripts/plot/barh.m, scripts/plot/box.m,
scripts/plot/caxis.m, scripts/plot/cla.m, scripts/plot/clabel.m,
scripts/plot/clf.m, scripts/plot/close.m, scripts/plot/colorbar.m,
scripts/plot/daspect.m, scripts/plot/ezmesh.m, scripts/plot/ezmeshc.m,
scripts/plot/ezsurf.m, scripts/plot/ezsurfc.m, scripts/plot/findall.m,
scripts/plot/findobj.m, scripts/plot/gcbo.m, scripts/plot/gcf.m,
scripts/plot/gco.m, scripts/plot/grid.m, scripts/plot/guihandles.m,
scripts/plot/hdl2struct.m, scripts/plot/hidden.m, scripts/plot/hold.m,
scripts/plot/isonormals.m, scripts/plot/isosurface.m, scripts/plot/legend.m,
scripts/plot/mesh.m, scripts/plot/meshc.m, scripts/plot/meshz.m,
scripts/plot/newplot.m, scripts/plot/orient.m, scripts/plot/pareto.m,
scripts/plot/patch.m, scripts/plot/pbaspect.m, scripts/plot/pcolor.m,
scripts/plot/plot.m, scripts/plot/print.m,
scripts/plot/private/__add_default_menu__.m, scripts/plot/quiver.m,
scripts/plot/quiver3.m, scripts/plot/refreshdata.m, scripts/plot/saveas.m,
scripts/plot/scatter.m, scripts/plot/scatter3.m, scripts/plot/shading.m,
scripts/plot/shrinkfaces.m, scripts/plot/slice.m, scripts/plot/stem.m,
scripts/plot/stem3.m, scripts/plot/struct2hdl.m, scripts/plot/subplot.m,
scripts/plot/surf.m, scripts/plot/surfc.m, scripts/plot/surfl.m,
scripts/plot/tetramesh.m, scripts/plot/uigetfile.m, scripts/plot/uimenu.m,
scripts/plot/uiputfile.m, scripts/plot/waterfall.m, scripts/plot/whitebg.m,
scripts/plot/xlim.m, scripts/plot/ylim.m, scripts/plot/zlim.m,
scripts/polynomial/conv.m, scripts/polynomial/polyout.m,
scripts/polynomial/splinefit.m, scripts/set/ismember.m, scripts/set/powerset.m,
scripts/set/setdiff.m, scripts/set/union.m, scripts/set/unique.m,
scripts/signal/detrend.m, scripts/signal/filter2.m, scripts/signal/freqz.m,
scripts/signal/periodogram.m, scripts/signal/spectral_adf.m,
scripts/signal/spectral_xdf.m, scripts/sparse/eigs.m, scripts/sparse/svds.m,
scripts/specfun/legendre.m, scripts/special-matrix/gallery.m,
scripts/statistics/base/mean.m, scripts/statistics/base/moment.m,
scripts/statistics/tests/cor_test.m,
scripts/statistics/tests/kolmogorov_smirnov_test.m,
scripts/statistics/tests/kolmogorov_smirnov_test_2.m,
scripts/statistics/tests/kruskal_wallis_test.m,
scripts/statistics/tests/prop_test_2.m, scripts/statistics/tests/sign_test.m,
scripts/statistics/tests/t_test.m, scripts/statistics/tests/t_test_2.m,
scripts/statistics/tests/t_test_regression.m,
scripts/statistics/tests/u_test.m, scripts/statistics/tests/var_test.m,
scripts/statistics/tests/welch_test.m,
scripts/statistics/tests/wilcoxon_test.m, scripts/statistics/tests/z_test.m,
scripts/statistics/tests/z_test_2.m, scripts/strings/base2dec.m,
scripts/strings/index.m, scripts/strings/isstrprop.m,
scripts/strings/mat2str.m, scripts/strings/regexptranslate.m,
scripts/strings/rindex.m, scripts/strings/str2num.m, scripts/strings/strcat.m,
scripts/strings/strjust.m, scripts/strings/strmatch.m,
scripts/strings/validatestring.m, scripts/testfun/demo.m,
scripts/testfun/example.m, scripts/testfun/test.m, scripts/time/addtodate.m,
scripts/time/asctime.m, scripts/time/datestr.m, scripts/time/datetick.m,
scripts/time/weekday.m, scripts/ui/errordlg.m, scripts/ui/helpdlg.m,
scripts/ui/inputdlg.m, scripts/ui/listdlg.m, scripts/ui/msgbox.m,
scripts/ui/questdlg.m, scripts/ui/warndlg.m: Use new @qcode macro.
author | Rik <rik@octave.org> |
---|---|
date | Mon, 19 Aug 2013 20:46:38 -0700 |
parents | d53fa7e43aa9 |
children | 4d7f95eb8bfe |
rev | line source |
---|---|
14138
72c96de7a403
maint: update copyright notices for 2012
John W. Eaton <jwe@octave.org>
parents:
14093
diff
changeset
|
1 @c Copyright (C) 2008-2012 David Bateman |
9602
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
2 @c Copyright (C) 2009 VZLU Prague |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
3 @c |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
4 @c This file is part of Octave. |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
5 @c |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
6 @c Octave is free software; you can redistribute it and/or modify it |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
7 @c under the terms of the GNU General Public License as published by the |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
8 @c Free Software Foundation; either version 3 of the License, or (at |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
9 @c your option) any later version. |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
10 @c |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
11 @c Octave is distributed in the hope that it will be useful, but WITHOUT |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
12 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
13 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
14 @c for more details. |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
15 @c |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
16 @c You should have received a copy of the GNU General Public License |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
17 @c along with Octave; see the file COPYING. If not, see |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
18 @c <http://www.gnu.org/licenses/>. |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
19 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
20 @c FIXME |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
21 @c For now can't include "@" character in the path name, and so name |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
22 @c the example directory without the "@"!! |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
23 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
24 @node Object Oriented Programming |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
25 @chapter Object Oriented Programming |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
26 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
27 Octave includes the capability to include user classes, including the |
9073 | 28 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
|
29 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
|
30 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
|
31 issue of class precedence in mixed class operations. |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
32 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
33 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
|
34 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
|
35 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
|
36 functions. |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
37 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
38 @menu |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
39 * Creating a Class:: |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
40 * Manipulating Classes:: |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
41 * Indexing Objects:: |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
42 * Overloading Objects:: |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
43 * Inheritance and Aggregation:: |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
44 @end menu |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
45 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
46 @node Creating a Class |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
47 @section Creating a Class |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
48 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
49 We use in the following text a polynomial class to demonstrate the use |
9073 | 50 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
|
51 it is simple, and so doesn't distract unnecessarily from the |
9073 | 52 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
|
53 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
|
54 fully grasp the techniques described. |
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 | 72 $a_0$, $a_1$, etc. are elements of $\Re$. |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
73 @end tex |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
74 @ifnottex |
9073 | 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 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
83 We therefore now have sufficient information about the requirements of |
9073 | 84 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
|
85 oriented classes in Octave, must be contained with a directory taking |
9073 | 86 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
|
87 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
|
88 the @@polynomial directory. |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
89 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
90 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
|
91 and so in our example the constructor with have the name |
9073 | 92 @file{@@polynomial/polynomial.m}. Also ideally when the constructor is |
93 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
|
94 our polynomial might look like |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
95 |
9906 | 96 @example |
97 @group | |
98 @EXAMPLEFILE(@polynomial/polynomial.m) | |
99 @end group | |
100 @end example | |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
101 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
102 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
|
103 the @code{class} function called with the first argument being a |
9073 | 104 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
|
105 the call to this constructor function is then |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
106 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
107 @example |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
108 p = polynomial ([1, 0, 1]); |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
109 @end example |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
110 |
9073 | 111 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
|
112 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
|
113 for the polynomial constructor @code{help polynomial} will return the |
9073 | 114 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
|
115 for the help to a particular class, for example @code{help |
9073 | 116 @@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
|
117 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
|
118 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
119 The same is true for other Octave functions that take a function name |
9073 | 120 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
|
121 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
|
122 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
|
123 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
|
124 class. |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
125 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
126 To check where a variable is 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
|
127 @code{isa} functions can be used. For example: |
8223
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 @example |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
130 @group |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
131 p = polynomial ([1, 0, 1]); |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
132 isobject (p) |
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 isa (p, "polynomial") |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12951
diff
changeset
|
135 @result{} 1 |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
136 @end group |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
137 @end 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 @DOCSTRING(isobject) |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
140 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
141 @noindent |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
142 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
|
143 @code{methods} function. |
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 @DOCSTRING(methods) |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
146 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
147 @noindent |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
148 To inquire whether a particular method is available to a user class, the |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
149 @code{ismethod} function can be used. |
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 @DOCSTRING(ismethod) |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
152 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
153 @noindent |
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
154 For example: |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
155 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
156 @example |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
157 @group |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
158 p = polynomial ([1, 0, 1]); |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
159 ismethod (p, "roots") |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12951
diff
changeset
|
160 @result{} 1 |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
161 @end group |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
162 @end example |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
163 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
164 @node Manipulating Classes |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
165 @section Manipulating Classes |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
166 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
167 There are a number of basic classes methods that can be defined to allow |
9073 | 168 the contents of the classes to be queried and set. The most basic of |
169 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
|
170 by Octave when displaying a class on the screen, due to an expression |
9073 | 171 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
|
172 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
|
173 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
174 @DOCSTRING(display) |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
175 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
176 @noindent |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
177 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
|
178 |
9906 | 179 @example |
180 @group | |
181 @EXAMPLEFILE(@polynomial/display.m) | |
182 @end group | |
183 @end example | |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
184 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
185 @noindent |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
186 Note that in the display method, it makes sense to start the method |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14846
diff
changeset
|
187 with the line @code{fprintf ("%s =", inputname (1))} to be consistent |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
188 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
|
189 when displaying the class. |
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 To be consistent with the Octave graphic handle classes, a class |
9073 | 192 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
|
193 @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
|
194 argument of the appropriate class it should return a structure with |
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
195 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
|
196 |
9906 | 197 @example |
198 @group | |
199 @EXAMPLEFILE(@polynomial/get.m) | |
200 @end group | |
201 @end 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 @noindent |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
204 Similarly, the @code{set} method should taken as its first argument an |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
205 object to modify, and then take property/value pairs to be modified. |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
206 |
9906 | 207 @example |
208 @group | |
209 @EXAMPLEFILE(@polynomial/set.m) | |
210 @end group | |
211 @end example | |
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 @noindent |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
214 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
|
215 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
|
216 must be called like |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
217 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
218 @example |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
219 p = set (p, "a", [1, 0, 0, 0, 1]); |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
220 @end example |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
221 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
222 @noindent |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
223 Also the @code{set} method makes use of the @code{subsasgn} method of |
9073 | 224 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
|
225 is discussed in the next section. |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
226 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
227 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
|
228 structure, and so they can be saved to a file in the same manner as a |
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
229 structure. For example: |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
230 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
231 @example |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
232 @group |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
233 p = polynomial ([1, 0, 1]); |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
234 save userclass.mat p |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
235 clear p |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
236 load userclass.mat |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
237 @end group |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
238 @end example |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
239 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
240 @noindent |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
241 All of the file formats supported by @code{save} and @code{load} are |
9073 | 242 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
|
243 a field that it makes no sense to save or a field that needs to be |
9073 | 244 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
|
245 @code{saveobj} method of the class |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
246 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
247 @DOCSTRING(saveobj) |
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 @noindent |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
250 @code{saveobj} is called just prior to saving the class to a |
9073 | 251 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
|
252 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
|
253 fields are reinserted into the user object. |
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 @DOCSTRING(loadobj) |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
256 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
257 @node Indexing Objects |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
258 @section Indexing Objects |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
259 |
9602
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
260 @menu |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
261 * Defining Indexing And Indexed Assignment:: |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
262 * Indexed Assignment Optimization:: |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
263 @end menu |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
264 |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
265 @node Defining Indexing And Indexed Assignment |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
266 @subsection Defining Indexing And Indexed Assignment |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
267 |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
268 Objects can be indexed with parentheses, either like |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
269 @code{@var{a} (@var{idx})} or like @code{@var{a} @{@var{idx}@}}, or even |
9073 | 270 like @code{@var{a} (@var{idx}).@var{field}}. However, it is up to the user |
271 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
|
272 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
|
273 @var{n}-th power of the polynomial, or it might be the evaluation of the |
9073 | 274 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
|
275 determined by the @code{subsref} method. |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
276 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
277 @DOCSTRING(subsref) |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
278 |
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
15997
diff
changeset
|
279 For example we might decide that indexing with @qcode{"()"} evaluates the |
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
15997
diff
changeset
|
280 polynomial and indexing with @qcode{"@{@}"} returns the @var{n}-th coefficient |
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
15997
diff
changeset
|
281 (of @var{n}-th power). In this case the @code{subsref} method of our |
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
15997
diff
changeset
|
282 polynomial class might look like |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
283 |
9906 | 284 @example |
285 @group | |
286 @EXAMPLEFILE(@polynomial/subsref.m) | |
287 @end group | |
288 @end example | |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
289 |
9073 | 290 The equivalent functionality for subscripted assignments uses the |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
291 @code{subsasgn} method. |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
292 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
293 @DOCSTRING(subsasgn) |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
294 |
12534
5b9b2645db26
Add optimize_subsasgn_calls function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
12448
diff
changeset
|
295 @DOCSTRING(optimize_subsasgn_calls) |
5b9b2645db26
Add optimize_subsasgn_calls function to documentation.
Rik <octave@nomad.inbox5.com>
parents:
12448
diff
changeset
|
296 |
9285
226f6d001ee2
further improve the polynomial example, fix indexing
Jaroslav Hajek <highegg@gmail.com>
parents:
9251
diff
changeset
|
297 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
|
298 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
|
299 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
|
300 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
|
301 |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
302 If you wish to use the @code{end} keyword in subscripted expressions |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
303 of an object, then the user needs to define the @code{end} method for |
12448
f2c080bbd8a5
Fix documentation bugs uncovered while rewriting munge-texi.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
304 the class. For example, the @code{end} method for our polynomial class might |
f2c080bbd8a5
Fix documentation bugs uncovered while rewriting munge-texi.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
305 look like |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
306 |
9906 | 307 @example |
308 @group | |
309 @EXAMPLEFILE(@polynomial/end.m) | |
310 @end group | |
311 @end example | |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
312 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
313 @noindent |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
314 which is a fairly generic @code{end} method that has a behavior similar to |
12448
f2c080bbd8a5
Fix documentation bugs uncovered while rewriting munge-texi.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
315 the @code{end} keyword for Octave Array classes. It can then be used as |
f2c080bbd8a5
Fix documentation bugs uncovered while rewriting munge-texi.
Rik <octave@nomad.inbox5.com>
parents:
11573
diff
changeset
|
316 follows: |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
317 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
318 @example |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
319 @group |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14846
diff
changeset
|
320 p = polynomial ([1,2,3,4]); |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
321 p(end-1) |
14093
050bc580cb60
doc: Various docstring improvements before 3.6.0 release.
Rik <octave@nomad.inbox5.com>
parents:
12951
diff
changeset
|
322 @result{} 3 |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
323 @end group |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
324 @end example |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
325 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
326 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
|
327 and this is controlled with the @code{subsindex} function. |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
328 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
329 @DOCSTRING(subsindex) |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
330 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
331 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
|
332 method |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
333 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
334 @DOCSTRING(colon) |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
335 |
9602
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
336 @node Indexed Assignment Optimization |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
337 @subsection Indexed Assignment Optimization |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
338 |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
339 Octave's ubiquitous lazily-copied pass-by-value semantics implies |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
340 a problem for performance of user-defined subsasgn methods. Imagine |
9602
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
341 a call to subsasgn: |
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 |
9602
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
345 ss = substruct ("()",@{1@}); |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
346 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
|
347 @end group |
9602
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
348 @end example |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
349 |
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
350 @noindent |
9602
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
351 and the corresponding method looking like this: |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
352 |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
353 @example |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
354 @group |
9602
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
355 function x = subsasgn (x, ss, val) |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
356 @dots{} |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14846
diff
changeset
|
357 x.myfield (ss.subs@{1@}) = val; |
9602
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
358 endfunction |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
359 @end group |
9602
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
360 @end example |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
361 |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
362 The problem is that on entry to the subsasgn method, @code{x} is still |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
363 referenced from the caller's scope, which means that the method will |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
364 first need to unshare (copy) @code{x} and @code{x.myfield} before performing |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
365 the assignment. Upon completing the call, unless an error occurs, |
9602
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
366 the result is immediately assigned to @code{x} in the caller's scope, |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
367 so that the previous value of @code{x.myfield} is forgotten. Hence, the |
9602
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
368 Octave language implies a copy of N elements (N being the size of |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
369 @code{x.myfield}), where modifying just a single element would actually |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
370 suffice, i.e., degrades a constant-time operation to linear-time one. |
9602
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
371 This may be a real problem for user classes that intrinsically store large |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
372 arrays. |
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 To partially solve the problem, Octave uses a special optimization for |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
375 user-defined subsasgn methods coded as m-files. When the method |
9602
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
376 gets called as a result of the built-in assignment syntax (not direct subsasgn |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
377 call as shown above), i.e. |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
378 |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
379 @example |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
380 x(1) = 1; |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
381 @end example |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
382 |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
383 @b{AND} if the subsasgn method is declared with identical input and output argument, |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
384 like in the example above, then Octave will ignore the copy of @code{x} inside |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
385 the caller's scope; therefore, any changes made to @code{x} during the method |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
386 execution will directly affect the caller's copy as well. |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
387 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
|
388 element takes constant time. |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
389 |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
390 It is important to understand the implications that this optimization brings. |
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
391 Since no extra copy of @code{x} in the caller's scope will exist, it is |
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
392 @emph{solely} the callee's responsibility to not leave @code{x} in an invalid |
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
393 state if an error occurs throughout the execution. Also, if the method |
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
394 partially changes @code{x} and then errors out, the changes @emph{will} affect |
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
395 @code{x} in the caller's scope. Deleting or completely replacing @code{x} |
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
396 inside 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
|
397 |
10846
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
398 Since this optimization may change the way code works (especially if badly |
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
399 written), a built-in variable @code{optimize_subsasgn_calls} is provided to |
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
400 control it. It is on by default. Another option to avoid the effect is to |
a4f482e66b65
Grammarcheck more of the documentation.
Rik <octave@nomad.inbox5.com>
parents:
10791
diff
changeset
|
401 declare subsasgn methods with different output and input arguments, like this: |
9602
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
402 |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
403 @example |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
404 @group |
9602
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
405 function y = subsasgn (x, ss, val) |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
406 @dots{} |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
407 endfunction |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
408 @end group |
9602
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
409 @end example |
dba091e1ee39
document subsasgn optimization in the OOP chapter
Jaroslav Hajek <highegg@gmail.com>
parents:
9285
diff
changeset
|
410 |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
411 @node Overloading Objects |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
412 @section Overloading Objects |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
413 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
414 @menu |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
415 * Function Overloading:: |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
416 * Operator Overloading:: |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
417 * Precedence of Objects:: |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
418 @end menu |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
419 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
420 @node Function Overloading |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
421 @subsection Function Overloading |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
422 |
11573
6f8ffe2c6f76
Grammarcheck txi files for 3.4 release.
Rik <octave@nomad.inbox5.com>
parents:
11523
diff
changeset
|
423 Any Octave function can be overloaded, and allows an object specific |
9073 | 424 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
|
425 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
|
426 like |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
427 |
9906 | 428 @example |
429 @group | |
430 @EXAMPLEFILE(@polynomial/polyval.m) | |
431 @end group | |
432 @end example | |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
433 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
434 This function just hands off the work to the normal Octave @code{polyval} |
9073 | 435 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
|
436 polynomial class is the @code{plot} function. |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
437 |
9906 | 438 @example |
439 @group | |
440 @EXAMPLEFILE(@polynomial/plot.m) | |
441 @end group | |
442 @end example | |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
443 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
444 @noindent |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
445 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
|
446 of the roots of the polynomial. |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
447 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
448 Functions that are of particular interest to be overloaded are the class |
9073 | 449 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
|
450 allows the @code{cast} function to work with the user class and can aid |
9073 | 451 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
|
452 @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
|
453 |
9906 | 454 @example |
455 @group | |
456 @EXAMPLEFILE(@polynomial/double.m) | |
457 @end group | |
458 @end example | |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
459 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
460 @node Operator Overloading |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
461 @subsection Operator Overloading |
11403
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
462 @cindex addition |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
463 @cindex and operator |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
464 @cindex arithmetic operators |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
465 @cindex boolean expressions |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
466 @cindex boolean operators |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
467 @cindex comparison expressions |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
468 @cindex complex-conjugate transpose |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
469 @cindex division |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
470 @cindex equality operator |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
471 @cindex equality, tests for |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
472 @cindex exponentiation |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
473 @cindex expressions, boolean |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
474 @cindex expressions, comparison |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
475 @cindex expressions, logical |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
476 @cindex greater than operator |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
477 @cindex Hermitian operator |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
478 @cindex less than operator |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
479 @cindex logical expressions |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
480 @cindex logical operators |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
481 @cindex matrix multiplication |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
482 @cindex multiplication |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
483 @cindex negation |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
484 @cindex not operator |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
485 @cindex operators, arithmetic |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
486 @cindex operators, boolean |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
487 @cindex operators, logical |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
488 @cindex operators, relational |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
489 @cindex or operator |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
490 @cindex quotient |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
491 @cindex relational operators |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
492 @cindex subtraction |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
493 @cindex tests for equality |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
494 @cindex transpose |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
495 @cindex transpose, complex-conjugate |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
496 @cindex unary minus |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
497 |
15568
38e64d9f0fda
doc: Workaround text overlap in pdf documentation caused by bug in Texinfo.
Rik <rik@octave.org>
parents:
14856
diff
changeset
|
498 @c Need at least one plaintext sentence here between the @node and @float |
38e64d9f0fda
doc: Workaround text overlap in pdf documentation caused by bug in Texinfo.
Rik <rik@octave.org>
parents:
14856
diff
changeset
|
499 @c table below or the two will overlap due to a bug in Texinfo. |
38e64d9f0fda
doc: Workaround text overlap in pdf documentation caused by bug in Texinfo.
Rik <rik@octave.org>
parents:
14856
diff
changeset
|
500 @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
|
501 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
|
502 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
|
503 user class. |
38e64d9f0fda
doc: Workaround text overlap in pdf documentation caused by bug in Texinfo.
Rik <rik@octave.org>
parents:
14856
diff
changeset
|
504 |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
505 @float Table,tab:overload_ops |
11403
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
506 @opindex + |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
507 @opindex - |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
508 @opindex .* |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
509 @opindex * |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
510 @opindex ./ |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
511 @opindex / |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
512 @opindex .\ |
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 .^ |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
515 @opindex ^ |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
516 @opindex < |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
517 @opindex <= |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
518 @opindex > |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
519 @opindex >= |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
520 @opindex == |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
521 @opindex != |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
522 @opindex ~= |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
523 @opindex & |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
524 @opindex | |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
525 @opindex ! |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
526 @opindex ' |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
527 @opindex .' |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
528 @opindex : |
b8b08b1ac21f
Add missing operator functions to doc/interpreter.
Judd Storrs <jstorrs@gmail.com>
parents:
11377
diff
changeset
|
529 @opindex < |
8286
6f2d95255911
fix @seealso references to point to existing anchors
Thorsten Meyer <thorsten.meyier@gmx.de>
parents:
8256
diff
changeset
|
530 |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
531 @tex |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
532 \vskip 6pt |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
533 {\hbox to \hsize {\hfill\vbox{\offinterlineskip \tabskip=0pt |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
534 \halign{ |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
535 \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
|
536 # \hfil & \vrule # & # \hfil & \vrule # & # \hfil & # \vrule |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
537 width 0.6pt \tabskip=0pt\cr |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
538 \noalign{\hrule height 0.6pt} |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
539 & Operation && Method && Description &\cr |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
540 \noalign{\hrule} |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
541 & $a + b$ && plus (a, b) && Binary addition operator&\cr |
8295 | 542 & $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
|
543 & $+ a$ && uplus (a) && Unary addition operator&\cr |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
544 & $- a$ && uminus (a) && Unary subtraction operator&\cr |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
545 & $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
|
546 & $a * b$ && mtimes (a, b) && Matrix multiplication operator&\cr |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
547 & $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
|
548 & $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
|
549 & $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
|
550 & $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
|
551 & $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
|
552 & $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
|
553 & $a < b$ && lt (a, b) && Less than operator&\cr |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
554 & $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
|
555 & $a > b$ && gt (a, b) && Greater than operator&\cr |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
556 & $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
|
557 & $a == b$ && eq (a, b) && Equal to operator&\cr |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
558 & $a != b$ && ne (a, b) && Not equal to operator&\cr |
14808 | 559 & $a \& b$ && and (a, b) && Logical and operator&\cr |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
560 & $a | b$ && or (a, b) && Logical or operator&\cr |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
561 & $! b$ && not (a) && Logical not operator&\cr |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
562 & $a'$ && ctranspose (a) && Complex conjugate transpose operator &\cr |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
563 & $a.'$ && transpose (a) && Transpose operator &\cr |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
564 & $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
|
565 & $a : b : c$ && colon (a, b, c) && Three element range operator &\cr |
9073 | 566 & $[a, b]$ && horzcat (a, b) && Horizontal concatenation operator &\cr |
567 & $[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
|
568 & $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
|
569 & $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
|
570 & $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
|
571 & {\it display} && display (a) && Commandline display function &\cr |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
572 \noalign{\hrule height 0.6pt} |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
573 }}\hfill}} |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
574 @end tex |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
575 @ifnottex |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
576 @multitable @columnfractions .1 .20 .20 .40 .1 |
11447
76f15f3da207
Use @headitem macro to create column heads for @multitable entries.
Rik <octave@nomad.inbox5.com>
parents:
11403
diff
changeset
|
577 @headitem @tab Operation @tab Method @tab Description @tab |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
578 @item @tab a + b @tab plus (a, b) @tab Binary addition @tab |
11377
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
579 @item @tab a - b @tab minus (a, b) @tab Binary subtraction operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
580 @item @tab + a @tab uplus (a) @tab Unary addition operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
581 @item @tab - a @tab uminus (a) @tab Unary subtraction operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
582 @item @tab a .* b @tab times (a, b) @tab Element-wise multiplication operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
583 @item @tab a * b @tab mtimes (a, b) @tab Matrix multiplication operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
584 @item @tab a ./ b @tab rdivide (a, b) @tab Element-wise right division operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
585 @item @tab a / b @tab mrdivide (a, b) @tab Matrix right division operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
586 @item @tab a .\ b @tab ldivide (a, b) @tab Element-wise left division operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
587 @item @tab a \ b @tab mldivide (a, b) @tab Matrix left division operator @tab |
12951
818299a39ae1
oop.txi: Fix incorrect names for power and mpower operators
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
12534
diff
changeset
|
588 @item @tab a .^ b @tab power (a, b) @tab Element-wise power operator @tab |
818299a39ae1
oop.txi: Fix incorrect names for power and mpower operators
Jordi Gutiérrez Hermoso <jordigh@gmail.com>
parents:
12534
diff
changeset
|
589 @item @tab a ^ b @tab mpower (a, b) @tab Matrix power operator @tab |
11377
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
590 @item @tab a < b @tab lt (a, b) @tab Less than operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
591 @item @tab a <= b @tab le (a, b) @tab Less than or equal to operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
592 @item @tab a > b @tab gt (a, b) @tab Greater than operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
593 @item @tab a >= b @tab ge (a, b) @tab Greater than or equal to operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
594 @item @tab a == b @tab eq (a, b) @tab Equal to operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
595 @item @tab a != b @tab ne (a, b) @tab Not equal to operator @tab |
14808 | 596 @item @tab a & b @tab and (a, b) @tab Logical and operator @tab |
11377
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
597 @item @tab a | b @tab or (a, b) @tab Logical or operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
598 @item @tab ! b @tab not (a) @tab Logical not operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
599 @item @tab a' @tab ctranspose (a) @tab Complex conjugate transpose operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
600 @item @tab a.' @tab transpose (a) @tab Transpose operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
601 @item @tab a : b @tab colon (a, b) @tab Two element range operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
602 @item @tab a : b : c @tab colon (a, b, c) @tab Three element range operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
603 @item @tab [a, b] @tab horzcat (a, b) @tab Horizontal concatenation operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
604 @item @tab [a; b] @tab vertcat (a, b) @tab Vertical concatenation operator @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
605 @item @tab a(s_1, @dots{}, s_n) @tab subsref (a, s) @tab Subscripted reference @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
606 @item @tab a(s_1, @dots{}, s_n) = b @tab subsasgn (a, s, b) @tab Subscripted assignment @tab |
473e4adaa5a2
oop.txi: Redo table rendered incorrectly in Info environment.
Rik <octave@nomad.inbox5.com>
parents:
10846
diff
changeset
|
607 @item @tab b (a) @tab subsindex (a) @tab Convert to zero-based index @tab |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
608 @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
|
609 @end multitable |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
610 @end ifnottex |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
611 @caption{Available overloaded operators and their corresponding class method} |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
612 @end float |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
613 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
614 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
|
615 |
9906 | 616 @example |
617 @group | |
618 @EXAMPLEFILE(@polynomial/mtimes.m) | |
619 @end group | |
620 @end example | |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
621 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
622 @node Precedence of Objects |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
623 @subsection Precedence of Objects |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
624 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
625 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
|
626 case can easily arise that these functions are called with objects of |
9073 | 627 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
|
628 of which method of which class to call when there are mixed objects given |
9073 | 629 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
|
630 @code{inferiorto} functions can be used |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
631 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
632 @DOCSTRING(superiorto) |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
633 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
634 @DOCSTRING(inferiorto) |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
635 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
636 For example with our polynomial class consider the case |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
637 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
638 @example |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
639 2 * polynomial ([1, 0, 1]); |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
640 @end example |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
641 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
642 @noindent |
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
15997
diff
changeset
|
643 That mixes an object of the class @qcode{"double"} with an object of the class |
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
15997
diff
changeset
|
644 @qcode{"polynomial"}. In this case we like to ensure that the return type of |
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
15997
diff
changeset
|
645 the above is of the type @qcode{"polynomial"} and so we use the |
9073 | 646 @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
|
647 polynomial class constructor would be modified to be |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
648 |
9906 | 649 @example |
650 @group | |
651 @EXAMPLEFILE(@polynomial/polynomial_superiorto.m) | |
652 @end group | |
653 @end example | |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
654 |
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
655 Note that user classes always have higher precedence than built-in |
9073 | 656 Octave types. So in fact marking our polynomial class higher than the |
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
15997
diff
changeset
|
657 @qcode{"double"} class is in fact not necessary. |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
658 |
15997
d53fa7e43aa9
doc: what happens when two objects have same precedence
Carnë Draug <carandraug@octave.org>
parents:
15568
diff
changeset
|
659 When faced with two objects that have the same precedence, Octave will use the |
d53fa7e43aa9
doc: what happens when two objects have same precedence
Carnë Draug <carandraug@octave.org>
parents:
15568
diff
changeset
|
660 method of the object that appears first on the list of arguments. |
8223
0c91b9a17dcf
Commit missing files from previous change
David Bateman <dbateman@free.fr>
parents:
diff
changeset
|
661 |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
662 @node Inheritance and Aggregation |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
663 @section Inheritance and Aggregation |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
664 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
665 Using classes to build new classes is supported by octave through the |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
666 use of both inheritance and aggregation. |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
667 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
668 Class inheritance is provided by octave using the @code{class} |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
669 function in the class constructor. As in the case of the polynomial |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
670 class, the octave programmer will create a struct that contains the |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
671 data fields required by the class, and then call the class function to |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
672 indicate that an object is to be created from the struct. Creating a |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
673 child of an existing object is done by creating an object of the |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
674 parent class and providing that object as the third argument of the |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
675 class function. |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
676 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
677 This is easily demonstrated by example. Suppose the programmer needs |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
678 an FIR filter, i.e., a filter with a numerator polynomial but a unity |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
679 denominator polynomial. In traditional octave programming, this would |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
680 be performed as follows. |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
681 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
682 @example |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
683 @group |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
684 octave:1> x = [some data vector]; |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
685 octave:2> n = [some coefficient vector]; |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
686 octave:3> y = filter (n, 1, x); |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
687 @end group |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
688 @end example |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
689 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
690 The equivalent class could be implemented in a class directory |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
691 @@FIRfilter that is on the octave path. The constructor is a file |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
692 FIRfilter.m in the class directory. |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
693 |
9906 | 694 @example |
695 @group | |
696 @EXAMPLEFILE(@FIRfilter/FIRfilter.m) | |
697 @end group | |
698 @end example | |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
699 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
700 As before, the leading comments provide command-line documentation for |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
701 the class constructor. This constructor is very similar to the |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
702 polynomial class constructor, except that we pass a polynomial object |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
703 as the third argument to the class function, telling octave that the |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
704 FIRfilter class will be derived from the polynomial class. Our FIR |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
705 filter does not have any data fields, but we must provide a struct to |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
706 the @code{class} function. The @code{class} function will add an |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
707 element named polynomial to the object struct, so we simply add a |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
708 dummy element named polynomial as the first line of the constructor. |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
709 This dummy element will be overwritten by the class function. |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
710 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
711 Note further that all our examples provide for the case in which no |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
712 arguments are supplied. This is important since octave will call the |
9752
51c21837686f
Period spellcheck of Octave documentation to check and fix newly added DOCSTRINGS
Rik <rdrider0-list@yahoo.com>
parents:
9602
diff
changeset
|
713 constructor with no arguments when loading objects from save files to |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
714 determine the inheritance structure. |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
715 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
716 A class may be a child of more than one class (see the documentation |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
717 for the @code{class} function), and inheritance may be nested. There |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
718 is no limitation to the number of parents or the level of nesting |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
719 other than memory or other physical issues. |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
720 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
721 As before, we need a @code{display} method. A simple example might be |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
722 |
9906 | 723 @example |
724 @group | |
725 @EXAMPLEFILE(@FIRfilter/display.m) | |
726 @end group | |
727 @end example | |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
728 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
729 Note that we have used the polynomial field of the struct to display |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
730 the filter coefficients. |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
731 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
732 Once we have the class constructor and display method, we may create |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
733 an object by calling the class constructor. We may also check the |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
734 class type and examine the underlying structure. |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
735 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
736 @example |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
737 @group |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14846
diff
changeset
|
738 octave:1> f = FIRfilter (polynomial ([1 1 1]/3)) |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
739 f.polynomial = 0.333333 + 0.333333 * X + 0.333333 * X ^ 2 |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14846
diff
changeset
|
740 octave:2> class (f) |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
741 ans = FIRfilter |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14846
diff
changeset
|
742 octave:3> isa (f,"FIRfilter") |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
743 ans = 1 |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14846
diff
changeset
|
744 octave:4> isa (f,"polynomial") |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
745 ans = 1 |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14846
diff
changeset
|
746 octave:5> struct (f) |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
747 ans = |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
748 @{ |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
749 polynomial = 0.333333 + 0.333333 * X + 0.333333 * X ^ 2 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
750 @} |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
751 @end group |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
752 @end example |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
753 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
754 We only need to define a method to actually process data with our |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
755 filter and our class is usable. It is also useful to provide a means |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
756 of changing the data stored in the class. Since the fields in the |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
757 underlying struct are private by default, we could provide a mechanism |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
758 to access the fields. The @code{subsref} method may be used for both. |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
759 |
9906 | 760 @example |
761 @group | |
762 @EXAMPLEFILE(@FIRfilter/subsref.m) | |
763 @end group | |
764 @end example | |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
765 |
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
15997
diff
changeset
|
766 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
|
767 to the constructor. |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
768 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
769 @example |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
770 @group |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14846
diff
changeset
|
771 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
|
772 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
|
773 octave:4> y = f(x) |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
774 y = |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
775 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
776 0.33333 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
777 0.66667 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
778 1.00000 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
779 1.00000 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
780 1.00000 |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
781 @end group |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
782 @end example |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
783 |
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
15997
diff
changeset
|
784 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
|
785 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
786 @example |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
787 @group |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14846
diff
changeset
|
788 octave:1> f = FIRfilter (polynomial ([1 1 1]/3)); |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
789 octave:2> f.polynomial |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
790 ans = 0.333333 + 0.333333 * X + 0.333333 * X ^ 2 |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
791 @end group |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
792 @end example |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
793 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
794 In order to change the contents of the object, we need to define a |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
795 @code{subsasgn} method. For example, we may make the polynomial field |
10791
3140cb7a05a1
Add spellchecker scripts for Octave and run spellcheck of documentation
Rik <octave@nomad.inbox5.com>
parents:
9906
diff
changeset
|
796 publicly writable. |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
797 |
9906 | 798 @example |
799 @group | |
800 @EXAMPLEFILE(@FIRfilter/subsasgn.m) | |
801 @end group | |
802 @end example | |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
803 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
804 So that |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
805 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
806 @example |
9758
09da0bd91412
Periodic grammar check of Octave documentation files to ensure common format
Rik <rdrider0-list@yahoo.com>
parents:
9752
diff
changeset
|
807 @group |
14856
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14846
diff
changeset
|
808 octave:6> f = FIRfilter (); |
c3fd61c59e9c
maint: Use Octave coding conventions for cuddling parentheses in doc directory
Rik <octave@nomad.inbox5.com>
parents:
14846
diff
changeset
|
809 octave:7> f.polynomial = polynomial ([1 2 3]); |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
810 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
|
811 @end group |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
812 @end example |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
813 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
814 Defining the FIRfilter class as a child of the polynomial class |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
815 implies that and FIRfilter object may be used any place that a |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
816 polynomial may be used. This is not a normal use of a filter, so that |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
817 aggregation may be a more sensible design approach. In this case, the |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
818 polynomial is simply a field in the class structure. A class |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
819 constructor for this case might be |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
820 |
9906 | 821 @example |
822 @group | |
823 @EXAMPLEFILE(@FIRfilter/FIRfilter_aggregation.m) | |
824 @end group | |
825 @end example | |
9251
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
826 |
f8b8ab529913
improve OOP documentation
Robert T. Short <octave@phaselockedsystems.com>
parents:
9245
diff
changeset
|
827 For our example, the remaining class methods remain unchanged. |