/usr/share/doc/octave/octave.html/Class-Methods.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Class Methods (GNU Octave)</title>

<meta name="description" content="Class Methods (GNU Octave)">
<meta name="keywords" content="Class Methods (GNU Octave)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Object-Oriented-Programming.html#Object-Oriented-Programming" rel="up" title="Object Oriented Programming">
<link href="Indexing-Objects.html#Indexing-Objects" rel="next" title="Indexing Objects">
<link href="Creating-a-Class.html#Creating-a-Class" rel="prev" title="Creating a Class">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">


</head>

<body lang="en">
<a name="Class-Methods"></a>
<div class="header">
<p>
Next: <a href="Indexing-Objects.html#Indexing-Objects" accesskey="n" rel="next">Indexing Objects</a>, Previous: <a href="Creating-a-Class.html#Creating-a-Class" accesskey="p" rel="prev">Creating a Class</a>, Up: <a href="Object-Oriented-Programming.html#Object-Oriented-Programming" accesskey="u" rel="up">Object Oriented Programming</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Class-Methods-1"></a>
<h3 class="section">34.2 Class Methods</h3>

<p>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 <code>display</code> method.  The <code>display</code> 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&rsquo;t end with a semicolon.  If this
method is not defined, then Octave won&rsquo;t print anything when displaying the
contents of a class which can be confusing.
</p>
<a name="XREFdisplay"></a><dl>
<dt><a name="index-display"></a>: <em></em> <strong>display</strong> <em>(<var>obj</var>)</em></dt>
<dd><p>Display the contents of the object <var>obj</var>.
</p>
<p>The Octave interpreter calls the <code>display</code> 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:
</p>
<div class="example">
<pre class="example">myobj = myclass (&hellip;)
</pre></div>

<p>User-defined classes should overload the <code>display</code> 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.
</p>
<div class="example">
<pre class="example">myobj = myclass (&hellip;)
  &rArr; myobj = &lt;class myclass&gt;
</pre></div>


<p><strong>See also:</strong> <a href="Built_002din-Data-Types.html#XREFclass">class</a>, <a href="Defining-Indexing-And-Indexed-Assignment.html#XREFsubsref">subsref</a>, <a href="Defining-Indexing-And-Indexed-Assignment.html#XREFsubsasgn">subsasgn</a>.
</p></dd></dl>


<p>An example of a display method for the polynomial class might be
</p>
<div class="example">
<pre class="verbatim">function display (p)

  printf (&quot;%s =&quot;, inputname (1));

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

  if (first)
    printf (&quot; 0&quot;);
  endif
  printf (&quot;\n&quot;);

endfunction
</pre></div>

<p>Note that in the display method it makes sense to start the method with the
line <code>printf&nbsp;(&quot;%s&nbsp;=&quot;,&nbsp;inputname&nbsp;(1))</code><!-- /@w --> to be consistent with the rest
of Octave which prints the variable name to be displayed followed by the value.
</p>
<p>To be consistent with the Octave graphic handle classes, a class should also
define the <code>get</code> and <code>set</code> methods.  The <code>get</code> 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.
</p>
<div class="example">
<pre class="verbatim">function val = get (p, prop)

  if (nargin &lt; 1 || nargin &gt; 2)
    print_usage ();
  endif

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

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

endfunction
</pre></div>

<p>Similarly, the first argument to the <code>set</code> method should be an object and
any additional arguments should be property/value pairs.
</p>
<div class="example">
<pre class="verbatim">function pout = set (p, varargin)

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

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

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

endfunction
</pre></div>

<p>Note that Octave does not implement pass by reference; Therefore, to modify an
object requires an assignment statement using the return value from the
<code>set</code> method.
</p>
<div class="example">
<pre class="example">p = set (p, &quot;poly&quot;, [1, 0, 0, 0, 1]);
</pre></div>

<p>The <code>set</code> method makes use of the <code>subsasgn</code> method of the class, and
therefore this method must also be defined.  The <code>subsasgn</code> method is
discussed more thoroughly in the next section (see <a href="Indexing-Objects.html#Indexing-Objects">Indexing Objects</a>).
</p>
<p>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>
<div class="example">
<pre class="example">p = polynomial ([1, 0, 1]);
save userclass.mat p
clear p
load userclass.mat
</pre></div>

<p>All of the file formats supported by <code>save</code> and <code>load</code> are supported.
In certain circumstances a user class might contain a field that it doesn&rsquo;t
make sense to save, or a field that needs to be initialized before it is saved.
This can be done with the <code>saveobj</code> method of the class.
</p>
<a name="XREFsaveobj"></a><dl>
<dt><a name="index-saveobj"></a>: <em><var>b</var> =</em> <strong>saveobj</strong> <em>(<var>a</var>)</em></dt>
<dd><p>Method of a class to manipulate an object prior to saving it to a file.
</p>
<p>The function <code>saveobj</code> is called when the object <var>a</var> is saved
using the <code>save</code> function.  An example of the use of <code>saveobj</code>
might be to remove fields of the object that don&rsquo;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:
</p>
<div class="example">
<pre class="example">function b = saveobj (a)
  b = a;
  if (isempty (b.field))
     b.field = initfield (b);
  endif
endfunction
</pre></div>


<p><strong>See also:</strong> <a href="#XREFloadobj">loadobj</a>, <a href="Built_002din-Data-Types.html#XREFclass">class</a>.
</p></dd></dl>


<p><code>saveobj</code> is called just prior to saving the class to a file.  Similarly,
the <code>loadobj</code> 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.
</p>
<a name="XREFloadobj"></a><dl>
<dt><a name="index-loadobj"></a>: <em><var>b</var> =</em> <strong>loadobj</strong> <em>(<var>a</var>)</em></dt>
<dd><p>Method of a class to manipulate an object after loading it from a file.
</p>
<p>The function <code>loadobj</code> is called when the object <var>a</var> is loaded
using the <code>load</code> function.  An example of the use of <code>saveobj</code>
might be to add fields to an object that don&rsquo;t make sense to be saved.
For example:
</p>
<div class="example">
<pre class="example">function b = loadobj (a)
  b = a;
  b.addmissingfield = addfield (b);
endfunction
</pre></div>


<p><strong>See also:</strong> <a href="#XREFsaveobj">saveobj</a>, <a href="Built_002din-Data-Types.html#XREFclass">class</a>.
</p></dd></dl>


<hr>
<div class="header">
<p>
Next: <a href="Indexing-Objects.html#Indexing-Objects" accesskey="n" rel="next">Indexing Objects</a>, Previous: <a href="Creating-a-Class.html#Creating-a-Class" accesskey="p" rel="prev">Creating a Class</a>, Up: <a href="Object-Oriented-Programming.html#Object-Oriented-Programming" accesskey="u" rel="up">Object Oriented Programming</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
octave-doc 4.2.2-1ubuntu1 / usr / share / doc / octave / octave.html / Class-Methods.html
