Object Oriented Programming
***************************

Octave has the ability to create user-defined classes---including the capabilities of operator and function overloading.  Classes can protect internal properties so that they may not be altered accidentally which facilitates data encapsulation.  In addition, rules can be created to address the issue of class precedence in mixed class operations.

This chapter discusses the means of constructing a user class, how to query and set the properties of a class, and how to overload operators and functions. Throughout this chapter real code examples are given using a class designed for polynomials.

Creating a Class
================

This chapter illustrates user-defined classes and object oriented programming through a custom class designed for polynomials.  This class was chosen for its simplicity which does not distract unnecessarily from the discussion of the programming features of Octave.  Even so, a bit of background on the goals of the polynomial class is necessary before the syntax and techniques of Octave object oriented programming are introduced.

The polynomial class is used to represent polynomials of the form

     a0 + a1 * x + a2 * x^2 + ... + an * x^n

where a0, a1, etc. are real scalars. Thus the polynomial can be represented by a vector

     a = [a0, a1, a2, ..., an];

This is a sufficient specification to begin writing the constructor for the polynomial class.  All object oriented classes in Octave must be located in a directory that is the name of the class prepended with the @ symbol. For example, the polynomial class will have all of its methods defined in the @polynomial directory.

The constructor for the class must be the name of the class itself; in this example the constructor resides in the file @polynomial/polynomial.m. Ideally, even when the constructor is called with no arguments it should return a valid object.  A constructor for the polynomial class might look like

     (/polynomial.m)

Note that the return value of the constructor must be the output of the class function.  The first argument to the class function is a structure and the second is the name of the class itself.  An example of calling the class constructor to create an instance is

     p = polynomial ([1, 0, 1]);

Methods are defined by m-files in the class directory and can have embedded documentation the same as any other m-file.  The help for the constructor can be obtained by using the constructor name alone, that is, for the polynomial constructor help polynomial will return the help string.  Help can be restricted to a particular class by using the class directory name followed by the method.  For example, help @polynomial/polynomial is another way of displaying the help string for the polynomial constructor.  This second means is the only way to obtain help for the overloaded methods and functions of a class.

The same specification mechanism can be used wherever Octave expects a function name.  For example type @polynomial/display will print the code of the display method of the polynomial class to the screen, and dbstop @polynomial/display will set a breakpoint at the first executable line of the display method of the polynomial class.

To check whether a variable belongs to a user class, the isobject and isa functions can be used.  For example:

     p = polynomial ([1, 0, 1]);
     isobject (p)
       => 1
     isa (p, "polynomial")
       => 1

(isobject)

The available methods of a class can be displayed with the methods function.

(methods)

To inquire whether a particular method exists for a user class, the ismethod function can be used.

(ismethod)

For example:

     p = polynomial ([1, 0, 1]);
     ismethod (p, "roots")
       => 1

Class Methods
=============

There are a number of basic class methods that can (and should) be defined to allow the contents of the classes to be queried and set.  The most basic of these is the display method.  The display method is used by Octave whenever a class should be displayed on the screen.  Usually this is the result of an Octave expression that doesn't end with a semicolon.  If this method is not defined, then Octave won't print anything when displaying the contents of a class which can be confusing.

(display)

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

     (/display.m)

Note that in the display method it makes sense to start the method with the line printf ("%s =", inputname (1)) to be consistent with the rest of Octave which prints the variable name to be displayed followed by the value.

To be consistent with the Octave graphic handle classes, a class should also define the get and set methods.  The get method accepts one or two arguments.  The first argument is an object of the appropriate class.  If no second argument is given then the method should return a structure with all the properties of the class.  If the optional second argument is given it should be a property name and the specified property should be retrieved.

     (/get.m)

Similarly, the first argument to the set method should be an object and any additional arguments should be property/value pairs.

     (/set.m)

Note that Octave does not implement pass by reference; Therefore, to modify an object requires an assignment statement using the return value from the set method.

     p = set (p, "poly", [1, 0, 0, 0, 1]);

The set method makes use of the subsasgn method of the class, and therefore this method must also be defined.  The subsasgn method is discussed more thoroughly in the next section (see Indexing Objects).

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

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

All of the file formats supported by save and load are supported. In certain circumstances a user class might contain a field that it doesn't make sense to save, or a field that needs to be initialized before it is saved. This can be done with the saveobj method of the class.

(saveobj)

saveobj is called just prior to saving the class to a file.  Similarly, the 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.

(loadobj)

Indexing Objects
================

Defining Indexing And Indexed Assignment
----------------------------------------

Objects can be indexed with parentheses or braces, either like OBJ(IDX) or like OBJ{IDX}, or even like OBJ(IDX).FIELD.  However, it is up to the programmer to decide what this indexing actually means.  In the case of the polynomial class P(N) might mean either the coefficient of the N-th power of the polynomial, or it might be the evaluation of the polynomial at N.  The meaning of this subscripted referencing is determined by the subsref method.

(subsref)

For example, this class uses the convention that indexing with "()" evaluates the polynomial and indexing with "{}" returns the N-th coefficient (of the N-th power).  The code for the subsref method looks like

     (/subsref.m)

The equivalent functionality for subscripted assignments uses the subsasgn method.

(subsasgn)

(optimize_subsasgn_calls)

Note that the subsref and subsasgn methods always receive the whole index chain, while they usually handle only the first element.  It is the responsibility of these methods to handle the rest of the chain (if needed), usually by forwarding it again to subsref or subsasgn.

If you wish to use the end keyword in subscripted expressions of an object, then there must be an end method defined.  For example, the end method for the polynomial class might look like

     (/end.m)

which is a fairly generic end method that has a behavior similar to the end keyword for Octave Array classes.  An example using the polynomial class is then

     p = polynomial ([1,2,3,4]);
     p{end-1}
       => 3

Objects can also be used themselves as the index in a subscripted expression and this is controlled by the subsindex function.

(subsindex)

Finally, objects can be used like ranges by providing a colon method.

(colon)

Indexed Assignment Optimization
-------------------------------

Octave's ubiquitous lazily-copied pass-by-value semantics implies a problem for performance of user-defined subsasgn methods.  Imagine the following call to subsasgn

     ss = substruct ("()", {1});
     x = subsasgn (x, ss, 1);

where the corresponding method looking like this:

     function x = subsasgn (x, ss, val)
       ...
       x.myfield (ss.subs{1}) = val;
     endfunction

The problem is that on entry to the subsasgn method, x is still referenced from the caller's scope, which means that the method will first need to unshare (copy) x and x.myfield before performing the assignment.  Upon completing the call, unless an error occurs, the result is immediately assigned to x in the caller's scope, so that the previous value of x.myfield is forgotten.  Hence, the Octave language implies a copy of N elements (N being the size of x.myfield), where modifying just a single element would actually suffice.  In other words, a constant-time operation is degraded to linear-time one.  This may be a real problem for user classes that intrinsically store large arrays.

To partially solve the problem Octave uses a special optimization for user-defined subsasgn methods coded as m-files.  When the method gets called as a result of the built-in assignment syntax (not a direct subsasgn call as shown above), i.e., x(1) = 1,  AND if the subsasgn method is declared with identical input and output arguments, as in the example above, then Octave will ignore the copy of x inside the caller's scope; therefore, any changes made to x during the method execution will directly affect the caller's copy as well. This allows, for instance, defining a polynomial class where modifying a single element takes constant time.

It is important to understand the implications that this optimization brings. Since no extra copy of x will exist in the caller's scope, it is solely the callee's responsibility to not leave x in an invalid state if an error occurs during the execution.  Also, if the method partially changes x and then errors out, the changes will affect x in the caller's scope.  Deleting or completely replacing x inside subsasgn will not do anything, however, only indexed assignments matter.

Since this optimization may change the way code works (especially if badly written), a built-in variable optimize_subsasgn_calls is provided to control it.  It is on by default.  Another way to avoid the optimization is to declare subsasgn methods with different output and input arguments like this:

     function y = subsasgn (x, ss, val)
       ...
     endfunction

Overloading Objects
===================

Function Overloading
--------------------

Any Octave function can be overloaded, and this allows an object-specific version of a function to be called as needed.  A pertinent example for the polynomial class might be to overload the polyval function.

     (/polyval.m)

This function just hands off the work to the normal Octave polyval function.  Another interesting example of an overloaded function for the polynomial class is the plot function.

     (/plot.m)

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

Functions that are of particular interest for overloading are the class conversion functions such as double.  Overloading these functions allows the cast function to work with a user class.  It can also can aid in the use of a class object with methods and functions from other classes since the object can be transformed to the requisite input form for the new function. An example double function for the polynomial class might look like

     (/double.m)

Operator Overloading
--------------------

The following table shows, for each built-in numerical operation, the corresponding function name to use when providing an overloaded method for a user class.

  Operation   Method   Description
  a + b   plus (a, b)   Binary addition
  a - b   minus (a, b)   Binary subtraction operator
  + a   uplus (a)   Unary addition operator
  - a   uminus (a)   Unary subtraction operator
  a .* b   times (a, b)   Element-wise multiplication operator
  a * b   mtimes (a, b)   Matrix multiplication operator
  a ./ b   rdivide (a, b)   Element-wise right division operator
  a / b   mrdivide (a, b)   Matrix right division operator
  a .\ b   ldivide (a, b)   Element-wise left division operator
  a \ b   mldivide (a, b)   Matrix left division operator
  a .^ b   power (a, b)   Element-wise power operator
  a ^ b   mpower (a, b)   Matrix power operator
  a < b   lt (a, b)   Less than operator
  a <= b   le (a, b)   Less than or equal to operator
  a > b   gt (a, b)   Greater than operator
  a >= b   ge (a, b)   Greater than or equal to operator
  a == b   eq (a, b)   Equal to operator
  a != b   ne (a, b)   Not equal to operator
  a & b   and (a, b)   Logical and operator
  a | b   or (a, b)   Logical or operator
  ! b   not (a)   Logical not operator
  a'   ctranspose (a)   Complex conjugate transpose operator
  a.'   transpose (a)   Transpose operator
  a : b   colon (a, b)   Two element range operator
  a : b : c   colon (a, b, c)   Three element range operator
  [a, b]   horzcat (a, b)   Horizontal concatenation operator
  [a; b]   vertcat (a, b)   Vertical concatenation operator
  a(s_1, ..., s_n)   subsref (a, s)   Subscripted reference
  a(s_1, ..., s_n) = b   subsasgn (a, s, b)   Subscripted assignment
  b (a)   subsindex (a)   Convert to zero-based index
   display   display (a)   Commandline display function

Table: Available overloaded operators and their corresponding class method

An example mtimes method for the polynomial class might look like

     (/mtimes.m)

Precedence of Objects
---------------------

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

(superiorto)

(inferiorto)

With the polynomial class, consider the case

     2 * polynomial ([1, 0, 1]);

that mixes an object of the class "double" with an object of the class "polynomial".  In this case the return type should be "polynomial" and so the superiorto function is used in the class constructor.  In particular the polynomial class constructor would be modified to

     (/polynomial_superiorto.m)

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

When confronted with two objects of equal precedence, Octave will use the method of the object that appears first in the list of arguments.

Inheritance and Aggregation
===========================

Using classes to build new classes is supported by Octave through the use of both inheritance and aggregation.

Class inheritance is provided by Octave using the class function in the class constructor.  As in the case of the polynomial class, the Octave programmer will create a structure that contains the data fields required by the class, and then call the class function to indicate that an object is to be created from the structure.  Creating a child of an existing object is done by creating an object of the parent class and providing that object as the third argument of the class function.

This is most easily demonstrated by example.  Suppose the programmer needs a FIR filter, i.e., a filter with a numerator polynomial but a denominator of 1. In traditional Octave programming this would be performed as follows.

     octave:1> x = [some data vector];
     octave:2> n = [some coefficient vector];
     octave:3> y = filter (n, 1, x);

The equivalent behavior can be implemented as a class @FIRfilter.  The constructor for this class is the file FIRfilter.m in the class directory @FIRfilter.

     (/FIRfilter.m)

As before, the leading comments provide documentation for the class constructor.  This constructor is very similar to the polynomial class constructor, except that a polynomial object is passed as the third argument to the class function, telling Octave that the FIRfilter class will be derived from the polynomial class.  The FIR filter class itself does not have any data fields, but it must provide a struct to the class function. Given that the @polynomial constructor will add an element named POLYNOMIAL to the object struct, the @FIRfilter just initializes a struct with a dummy field POLYNOMIAL which will later be overwritten.

Note that the sample code always provides for the case in which no arguments are supplied.  This is important because Octave will call a constructor with no arguments when loading objects from saved files in order to determine the inheritance structure.

A class may be a child of more than one class (see class), and inheritance may be nested.  There is no limitation to the number of parents or the level of nesting other than memory or other physical issues.

As before, a class requires a display method.  A simple example might be

     (/display.m)

Note that the FIRfilter's display method relies on the display method from the polynomial class to actually display the filter coefficients.

Once a constructor and display method exist, it is possible to create an instance of the class.  It is also possible to check the class type and examine the underlying structure.

     octave:1> f = FIRfilter (polynomial ([1 1 1]/3))
     f.polynomial = 0.33333 + 0.33333 * X + 0.33333 * X ^ 2
     octave:2> class (f)
     ans = FIRfilter
     octave:3> isa (f, "FIRfilter")
     ans =  1
     octave:4> isa (f, "polynomial")
     ans =  1
     octave:5> struct (f)
     ans =

       scalar structure containing the fields:

     polynomial = 0.33333 + 0.33333 * X + 0.33333 * X ^ 2

The only thing remaining to make this class usable is a method for processing data.  But before that, it is usually desirable to also have a way of changing the data stored in a class.  Since the fields in the underlying struct are private by default, it is necessary to provide a mechanism to access the fields.  The subsref method may be used for both tasks.

     (/subsref.m)

The "()" case allows us to filter data using the polynomial provided to the constructor.

     octave:2> f = FIRfilter (polynomial ([1 1 1]/3));
     octave:3> x = ones (5,1);
     octave:4> y = f(x)
     y =

        0.33333
        0.66667
        1.00000
        1.00000
        1.00000

The "." case allows us to view the contents of the polynomial field.

     octave:1> f = FIRfilter (polynomial ([1 1 1]/3));
     octave:2> f.polynomial
     ans = 0.33333 + 0.33333 * X + 0.33333 * X ^ 2

In order to change the contents of the object a subsasgn method is needed.  For example, the following code makes the polynomial field publicly writable

     (/subsasgn.m)

so that

     octave:1> f = FIRfilter ();
     octave:2> f.polynomial = polynomial ([1 2 3])
     f.polynomial = 1 + 2 * X + 3 * X ^ 2

Defining the FIRfilter class as a child of the polynomial class implies that a FIRfilter object may be used any place that a polynomial object may be used.  This is not a normal use of a filter.  It may be a more sensible design approach to use aggregation rather than inheritance.  In this case, the polynomial is simply a field in the class structure.  A class constructor for the aggregation case might be

     (/FIRfilter_aggregation.m)

For this example only the constructor needs changing, and all other class methods stay the same.