Info Catalog octave: Object Oriented Programming octave: Class Methods

octave: Creating a Class

 
 34.1 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
 
      ## -*- texinfo -*-
      ## @deftypefn  {} {} polynomial ()
      ## @deftypefnx {} {} polynomial (@var{a})
      ## Create a polynomial object representing the polynomial
      ##
      ## @example
      ## a0 + a1 * x + a2 * x^2 + @dots{} + an * x^n
      ## @end example
      ##
      ## @noindent
      ## from a vector of coefficients [a0 a1 a2 @dots{} an].
      ## @end deftypefn
      
      function p = polynomial (a)
      
        if (nargin > 1)
          print_usage ();
        endif
      
        if (nargin == 0)
          p.poly = [0];
          p = class (p, "polynomial");
        else
          if (strcmp (class (a), "polynomial"))
            p = a;
          elseif (isreal (a) && isvector (a))
            p.poly = a(:).';  # force row vector
            p = class (p, "polynomial");
          else
            error ("@polynomial: A must be a real vector");
          endif
        endif
      
      endfunction
 
    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 (X)
      Return true if X is a class object.
 
      See also: class XREFclass, typeinfo XREFtypeinfo,
DONTPRINTYET       isa XREFisa, ismethod XREFismethod, *noteisprop:
DONTPRINTYET       isa XREFisa, ismethod XREFismethod, isprop

      XREFisprop.
 
 The available methods of a class can be displayed with the ‘methods’
 function.
 
  -- : methods (OBJ)
  -- : methods ("CLASSNAME")
  -- : MTDS = methods (...)
      List the names of the public methods for the object OBJ or the
      named class CLASSNAME.
 
      OBJ may be an Octave class object or a Java object.  CLASSNAME may
      be the name of an Octave class or a Java class.
 
      When called with no output arguments, ‘methods’ prints the list of
      method names to the screen.  Otherwise, the output argument MTDS
      contains the list in a cell array of strings.
 
      See also: fieldnames XREFfieldnames.
 
 To inquire whether a particular method exists for a user class, the
 ‘ismethod’ function can be used.
 
  -- : ismethod (OBJ, METHOD)
  -- : ismethod (CLSNAME, METHOD)
      Return true if the string METHOD is a valid method of the object
      OBJ or of the class CLSNAME.
 
      See also: isprop XREFisprop, isobject XREFisobject.
 
 For example:
 
      p = polynomial ([1, 0, 1]);
      ismethod (p, "roots")
        ⇒ 1
 

Info Catalog octave: Object Oriented Programming octave: Class Methods