34.2 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 (obj)

Display the contents of the object obj.

The Octave interpreter calls the display function whenever it needs to present a class on-screen. Typically, this would be a statement which does not end in a semicolon to suppress output. For example:

myobj = myclass (…)

User-defined classes should overload the display method so that something useful is printed for a class object. Otherwise, Octave will report only that the object is an instance of its class.

myobj = myclass (…)
  ⇒ myobj = <class myclass>

See also: class, subsref, subsasgn.

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

function display (p)

  printf ("%s =", inputname (1));

  a = p.poly;
  first = true;
  for i = 1 : length (a);
    if (a(i) != 0)
      if (first)
        first = false;
      elseif (a(i) > 0 || isnan (a(i)))
        printf (" +");
      endif
      if (a(i) < 0)
        printf (" -");
      endif
      if (i == 1)
        printf (" %.5g", abs (a(i)));
      elseif (abs (a(i)) != 1)
        printf (" %.5g *", abs (a(i)));
      endif
      if (i > 1)
        printf (" X");
      endif
      if (i > 2)
        printf (" ^ %d", i - 1);
      endif
    endif
  endfor

  if (first)
    printf (" 0");
  endif
  printf ("\n");

endfunction

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.

function val = get (p, prop)

  if (nargin < 1 || nargin > 2)
    print_usage ();
  endif

  if (nargin == 1)
    val.poly = p.poly;
  else
    if (! ischar (prop))
      error ("@polynomial/get: PROPERTY must be a string");
    endif

    switch (prop)
      case "poly"
        val = p.poly;
      otherwise
        error ('@polynomial/get: invalid PROPERTY "%s"', prop);
    endswitch
  endif

endfunction

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

function pout = set (p, varargin)

  if (numel (varargin) < 2 || rem (numel (varargin), 2) != 0)
    error ("@polynomial/set: expecting PROPERTY/VALUE pairs");
  endif

  pout = p;
  while (numel (varargin) > 1)
    prop = varargin{1};
    val  = varargin{2};
    varargin(1:2) = [];
    if (! ischar (prop) || ! strcmp (prop, "poly"))
      error ("@polynomial/set: invalid PROPERTY for polynomial class");
    elseif (! (isreal (val) && isvector (val)))
      error ("@polynomial/set: VALUE must be a real vector");
    endif

    pout.poly = val(:).';  # force row vector
  endwhile

endfunction

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.

: b = saveobj (a)

Method of a class to manipulate an object prior to saving it to a file.

The function saveobj is called when the object a is saved using the save function. An example of the use of saveobj might be to remove fields of the object that don’t make sense to be saved or it might be used to ensure that certain fields of the object are initialized before the object is saved. For example:

function b = saveobj (a)
  b = a;
  if (isempty (b.field))
     b.field = initfield (b);
  endif
endfunction

See also: loadobj, class.

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.

: b = loadobj (a)

Method of a class to manipulate an object after loading it from a file.

The function loadobj is called when the object a is loaded using the load function. An example of the use of saveobj might be to add fields to an object that don’t make sense to be saved. For example:

function b = loadobj (a)
  b = a;
  b.addmissingfield = addfield (b);
endfunction

See also: saveobj, class.