@c Copyright (C) 2008 David Bateman
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@c FIXME
@c For now can't include "@" character in the path name, and so name
@c the example directory without the "@"!!

@macro classfile{class, file}
@example
@group
@verbatiminclude @value{abs_top_srcdir}/examples/\class\/\file\
@end group
@end example
@end macro

@macro polynomialfile{file}
@classfile{@@polynomial,\file\}
@end macro

@node Object Oriented Programming
@chapter Object Oriented Programming

Octave includes the capability to include user classes, including the
features of operator and function overloading. Equally a user class
can be used to encapsulate certain properties of the class so that
they can not be altered accidentally and can be set up to address the
issue of class precedence in mixed class operations.

This chapter discussions the means of constructing a user class with
the example of a polynomial class, how to query and set the properties
of this class, together with the means to overload operators and
functions.

@menu
* Creating a Class::
* Manipulating Classes::
* Indexing Objects::
* Overloading Objects::
@end menu

@node Creating a Class
@section Creating a Class

We use in the following text a polynomial class to demonstrate the use
of object oriented programming within Octave. This class was chosen as
it is simple, and so doesn't distract unnecessarily from the
discussion of the programming features of Octave. However, even still
a small understand of the polynomial class itself is necessary to
fully grasp the techniques described.

The polynomial class is used to represent polynomials of the form

@example
@iftex
@tex
$a_0 + a_1 x + a_2 x^2 + \ldots a_n x^n$
@end tex
@end iftex
@ifnottex
a0 + a1 * x + a2 * x^2 + @dots{} + an * x^n
@end ifnottex
@end example

@noindent
where
@iftex
@tex
$a_0$, $a_1$, etc are elements of $\Re$.
@end tex
@end iftex
@ifnottex
a0, a1, etc are real scalars.
@end ifnottex
Thus the polynomial can be represented by a vector

@example
a = [a0, a1, a2, @dots{}, an];
@end example

We therefore now have sufficient information about the requirements of
the class constructor for our polynomial class to write it. All object
oriented classes in Octave, must be contained with a directory taking
the name of the class, prepended with the @@ symbol. For example, with
our polynomial class, we would place the methods defining the class in
the @@polynomial directory.

The constructor of the class, must have the name of the class itself
and so in our example the constructor with have the name
@file{@@polynomial/polynomial.m}. Also ideally when the constructor is
called with no arguments to should return a value object. So for example
our polynomial might look like

@polynomialfile{polynomial.m}

Note that the return value of the constructor must be the output of
the @code{class} function called with the first argument being a
structure and the second argument being the class name. An example of
the call to this constructor function is then

@example
p = polynomial ([1, 0, 1]);
@end example

Note that methods of a class can be documented. The help for the
constructor itself can be obtained with the constructor name, that is
for the polynomial constructor @code{help polynomial} will return the
help string. Also the help can be obtained by restricting the search
for the help to a particular class, for example @code{help
@@polynomial/polynomial}. This second method is the only means of
getting help for the overloaded methods and functions of the class.

The same is true for other Octave functions that take a function name
as an argument. For example @code{type @@polynomial/display} will
print the code of the display method of the polynomial class to the
screen, and @code{dbstop @@polynomial/display} will set a breakpoint
at the first executable line of the display method of the polynomial
class.

To check where a variable is a user class, the @code{isobject} and
@code{isa} functions can be used. for example

@example
@group
p = polynomial ([1, 0, 1]);
isobject (p)
@result{} 1
isa (p, "polynomial")
@result{} 1
@end group
@end example

@DOCSTRING(isobject)

@noindent
The available methods of a class can be displayed with the
@code{methods} function.

@DOCSTRING(methods)

@noindent
To enquiry whether a particular method is available to a user class, the
@code{ismethod} function can be used.

@DOCSTRING(ismethod)

@noindent
For example

@example
@group
p = polynomial ([1, 0, 1]);
ismethod (p, "roots")
@result{} 1
@end group
@end example

@node Manipulating Classes
@section Manipulating Classes

There are a number of basic classes methods that can be defined to allow
the contents of the classes to be queried and set. The most basic of
these is the @code{display} method. The @code{display} method is used
by Octave when displaying a class on the screen, due to an expression
that is not terminated with a semicolon. If this method is not defined,
then Octave will printed nothing when displaying the contents of a class.

@DOCSTRING(display)

@noindent
An example of a display method for the polynomial class might be

@polynomialfile{display.m}

@noindent
Note that in the display method, it makes sense to start the method
with the line @code{fprintf("%s =", inputname(1))} to be consistent
with the rest of Octave and print the variable name to be displayed
when displaying the class. 

To be consistent with the Octave graphic handle classes, a class
should also define the @code{get} and @code{set} methods. The
@code{get} method should accept one or two arguments, and given one
argument of the appropriate class it should return a structure with
all of the properties of the class. For example

@polynomialfile{get.m}

@noindent
Similarly, the @code{set} method should taken as its first argument an
object to modify, and then take property/value pairs to be modified. 

@polynomialfile{set.m}

@noindent
Note that as Octave does not implement pass by reference, than the
modified object is the return value of the @code{set} method and it
must be called like

@example
p = set (p, "a", [1, 0, 0, 0, 1]);
@end example

@noindent
Also the @code{set} method makes use of the @code{subsasgn} method of
the class, and this method must be defined. The @code{subsasgn} method
is discussed in the next section.

Finally, user classes can be considered as a special type of a
structure, and so they can be saved to a file in the same manner as a
structure. For example

@example
@group
p = polynomial ([1, 0, 1]);
save userclass.mat p
clear p
load userclass.mat
@end group
@end example

@noindent
All of the file formats supported by @code{save} and @code{load} are
supported. In certain circumstances, a user class might either contain
a field that it makes no sense to save or a field that needs to be
initialized before it is saved. This can be done with the
@code{saveobj} method of the class

@DOCSTRING(saveobj)

@noindent
@code{saveobj} is called just prior to saving the class to a
file. Likely, the @code{loadobj} method is called just after a class
is loaded from a file, and can be used to ensure that any removed
fields are reinserted into the user object.

@DOCSTRING(loadobj)

@node Indexing Objects
@section Indexing Objects

Objects in can be indexed with parenthesises, either like 
@code{@var{a} (@var{idx})} or like @code{@var{a} @{@var{idx}@}}, or even
like @code{@var{a} (@var{idx}).@var{field}}. However, it is up to the user
to decide what this indexing actually means. In the case of our polynomial
class @code{@var{p} (@var{n})} might mean either the coefficient of the 
@var{n}-th power of the polynomial, or it might be the evaluation of the 
polynomial at @var{n}. The meaning of this subscripted referencing is 
determined by the @code{subsref} method.

@DOCSTRING(subsref)

For example we might decide that indexing with "()" evaluates the
polynomial and indexing with "@{@}" returns the @var{n}-th coefficient.
In this case the @code{subsref} method of our polynomial class might look like

@polynomialfile{subsref.m}

The equivalent functionality for subscripted asignments uses the 
@code{subsasgn} method.

@DOCSTRING(subsasgn)

If you wish to use the @code{end} keyword in subscripted expressions
of an object. Then the user needs to define the @code{end} method for 
the class.

@DOCSTRING(end)

For example the @code{end} method for our polynomial class might look like

@polynomialfile{end.m}

@noindent
which is a fairly generic @code{end} method that has a behavior similar to
the @code{end} keyword for Octave Array classes. It can then be used for
example like

@example
@group
p = polynomial([1,2,3,4]);
p(end-1)
@result{} 3
@end group
@end example

Objects can also be used as the index in a subscripted expression themselves
and this is controlled with the @code{subsindex} function.

@DOCSTRING(subsindex)

Finally, objects can equally be used like ranges, using the @code{colon}
method

@DOCSTRING(colon)

@node Overloading Objects
@section Overloading Objects

@menu
* Function Overloading::
* Operator Overloading::
* Precedence of Objects::
@end menu

@node Function Overloading
@subsection Function Overloading

Any Octave function can be overloaded, and allows a object specific
version of this function to be called as needed. A pertinent example
for our polynomial class might be to overload the @code{polyval} function
like

@polynomialfile{polyval.m}

This function just hands off the work to the normal Octave @code{polyval}
function. Another interesting example for an overloaded function for our
polynomial class is the @code{plot} function.

@polynomialfile{plot.m}

@noindent
which allows polynomials to be plotted in the domain near the region
of the roots of the polynomial.

Functions that are of particular interest to be overloaded are the class
conversion functions such as @code{double}. Overloading these functions 
allows the @code{cast} function to work with the user class and can aid 
in the use of methods of other classes with the user class. An example
@code{double} function for our polynomial class might look like.

@polynomialfile{double.m}

@node Operator Overloading
@subsection Operator Overloading

@float Table,tab:overload_ops
@iftex
@tex
\vskip 6pt
{\hbox to \hsize {\hfill\vbox{\offinterlineskip \tabskip=0pt 
\halign{
\vrule height2.0ex depth1.ex width 0.6pt #\tabskip=0.3em &
# \hfil & \vrule # & # \hfil & \vrule # & # \hfil & # \vrule 
width 0.6pt \tabskip=0pt\cr
\noalign{\hrule height 0.6pt}
& Operation && Method && Description &\cr
\noalign{\hrule}
& $a + b$ && plus (a, b) && Binary addition operator&\cr
& $a - b$ && plus (a, b) && Binary subtraction operator&\cr
& $+ a$ && uplus (a) && Unary addition operator&\cr
& $- a$ && uminus (a) && Unary subtraction operator&\cr
& $a .* b$ && times (a, b) && Element-wise multiplication operator&\cr
& $a * b$ && mtimes (a, b) && Matrix multiplication operator&\cr
& $a ./ b$ && rdivide (a, b) && Element-wise right division operator&\cr
& $a / b$ && mrdivide (a, b) && Matrix right division operator&\cr
& $a .\backslash b$ && ldivide (a, b) && Element-wise left division operator&\cr
& $a \backslash b$ && mldivide (a, b) && Matrix left division operator&\cr
& $a .\hat b$ && power (a, b) && Element-wise power operator&\cr
& $a \hat b$ && mpower (a, b) && Matrix power operator&\cr
& $a < b$ && lt (a, b) && Less than operator&\cr
& $a <= b$ && le (a, b) && Less than or equal to operator&\cr
& $a > b$ && gt (a, b) && Greater than operator&\cr
& $a >= b$ && ge (a, b) && Greater than or equal to operator&\cr
& $a == b$ && eq (a, b) && Equal to operator&\cr
& $a != b$ && ne (a, b) && Not equal to operator&\cr
& $a \& b$ && and (a, b) && Logical and operator&\cr
& $a | b$ && or (a, b) && Logical or operator&\cr
& $! b$ && not (a) && Logical not operator&\cr
& $a'$ && ctranspose (a) && Complex conjugate transpose operator &\cr
& $a.'$ && transpose (a) && Transpose operator &\cr
& $a : b$ && colon (a, b) && Two element range operator &\cr
& $a : b : c$ && colon (a, b, c) && Three element range operator &\cr
& $[a, b]$ && horzcat (a, b) && Horizontal concatenation opertaor &\cr
& $[a; b]$ && vertcat (a, b) && Vertical concatenation opertaor &\cr
& $a(s_1, \ldots, s_n)$ && subsref (a, s) && Subscripted reference &\cr
& $a(s_1, \ldots, s_n) = b$ && subsasgn (a, s, b) && Subscripted assignment &\cr
& $b (a)$ && subsindex (a) && Convert to zero-based index &\cr
& {\it display} && display (a) && Commandline display function &\cr
\noalign{\hrule height 0.6pt}
}}\hfill}}
@end tex
@end iftex
@ifnottex
@multitable @columnfractions .1 .20 .20 .40 .1
@item @tab Operation @tab Method @tab Description @tab
@item @tab a + b @tab plus (a, b) @tab Binary addition @tab
@item @tab a - b$ @tab plus (a, b) @tab Binary subtraction operator @tab
@item @tab + a$ @tab uplus (a) @tab Unary addition operator @tab
@item @tab - a$ @tab uminus (a) @tab Unary subtraction operator @tab
@item @tab a .* b$ @tab times (a, b) @tab Element-wise multiplication operator @tab
@item @tab a * b$ @tab mtimes (a, b) @tab Matirx multiplication operator @tab
@item @tab a ./ b$ @tab rdivide (a, b) @tab Element-wise right division operator @tab
@item @tab a / b$ @tab mrdivide (a, b) @tab Matrix right division operator @tab
@item @tab a .\ b$ @tab ldivide (a, b) @tab Element-wise left division operator @tab
@item @tab a \ b$ @tab mldivide (a, b) @tab Matrix left division operator @tab
@item @tab a .^ b$ @tab ldivide (a, b) @tab Element-wise power operator @tab
@item @tab a ^ b$ @tab mldivide (a, b) @tab Matrix power operator @tab
@item @tab a < b$ @tab lt (a, b) @tab Less than operator @tab
@item @tab a <= b$ @tab le (a, b) @tab Less than or equal to operator @tab
@item @tab a > b$ @tab gt (a, b) @tab Greater than operator @tab
@item @tab a >= b$ @tab ge (a, b) @tab Greater than or equal to operator @tab
@item @tab a == b$ @tab eq (a, b) @tab Equal to operator @tab
@item @tab a != b$ @tab ne (a, b) @tab Not equal to operator @tab
@item @tab a \& b$ @tab and (a, b) @tab Logical and operator @tab
@item @tab a | b$ @tab or (a, b) @tab Logical or operator @tab
@item @tab ! b$ @tab not (a) @tab Logical not operator @tab
@item @tab a'$ @tab ctranspose (a) @tab Complex conjugate transpose operator @tab
@item @tab a.'$ @tab transpose (a) @tab Transpose operator @tab
@item @tab a : b$ @tab colon (a, b) @tab Two element range operator @tab
@item @tab a : b : c$ @tab colon (a, b, c) @tab Three element range operator @tab
@item @tab [a, b]$ @tab horzcat (a, b) @tab Horizontal concatenation opertaor @tab
@item @tab [a; b]$ @tab vertcat (a, b) @tab Vertical concatenation opertaor @tab
@item @tab a(s_1, \ldots, s_n)$ @tab subsref (a, s) @tab Subscripted reference @tab
@item @tab a(s_1, \ldots, s_n) = b$ @tab subsasgn (a, s, b) @tab Subscripted assignment @tab
@item @tab b (a)$ @tab subsindex (a) @tab Convert to zero-based index @tab
@item @tab  @dfn{display} @tab display (a) @tab Commandline display function @tab
@end multitable
@end ifnottex
@caption{Available overloaded operators and their corresponding class method}
@end float

An example @code{mtimes} method for our polynomial class might look like

@polynomialfile{mtimes.m}

@node Precedence of Objects
@subsection Precedence of Objects

Many functions and operators take two or more arguments and so the
case can easily arise that these functions are called with objects of
different classes. It is therefore necessary to determine the precedence
of which method of which class to call when there are mixed objects given
to a function or operator. To do this the @code{superiorto} and
@code{inferiorto} functions can be used

@DOCSTRING(superiorto)

@DOCSTRING(inferiorto)

For example with our polynomial class consider the case

@example
2 * polynomial ([1, 0, 1]);
@end example

@noindent
That mixes an object of the class "double" with an object of the class
"polynomial". In this case we like to ensure that the return type of
the above is of the type "polynomial" and so we use the
@code{superiorto} function in the class constructor. In particular our
polynomial class constructor would be modified to be

@polynomialfile{polynomial_superiorto.m}

Note that user classes always have higher precedence than built-in
Octave types. So in fact marking our polynomial class higher than the 
"double" class is in fact not necessary.