File: Class-Methods.html

package info (click to toggle)
octave 7.3.0-2
links: PTS, VCS
area: main
in suites: bookworm
size: 130,464 kB
sloc: cpp: 332,823; ansic: 71,320; fortran: 20,963; objc: 8,562; sh: 8,115; yacc: 4,882; lex: 4,438; perl: 1,554; java: 1,366; awk: 1,257; makefile: 652; xml: 173
file content (249 lines) | stat: -rw-r--r-- 9,503 bytes
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Class Methods (GNU Octave (version 7.3.0))</title>

<meta name="description" content="Class Methods (GNU Octave (version 7.3.0))">
<meta name="keywords" content="Class Methods (GNU Octave (version 7.3.0))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">

<link href="index.html" rel="start" title="Top">
<link href="Concept-Index.html" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Object-Oriented-Programming.html" rel="up" title="Object Oriented Programming">
<link href="Indexing-Objects.html" rel="next" title="Indexing Objects">
<link href="Creating-a-Class.html" rel="prev" title="Creating a Class">
<style type="text/css">
<!--
a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
div.display {margin-left: 3.2em}
div.example {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}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
span:hover a.copiable-anchor {visibility: visible}
ul.no-bullet {list-style: none}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">


</head>

<body lang="en">
<div class="section" id="Class-Methods">
<div class="header">
<p>
Next: <a href="Indexing-Objects.html" accesskey="n" rel="next">Indexing Objects</a>, Previous: <a href="Creating-a-Class.html" accesskey="p" rel="prev">Creating a Class</a>, Up: <a href="Object-Oriented-Programming.html" 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" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<span id="Class-Methods-1"></span><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>disp</code> method.  The <code>disp</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>
<p>An example of a <code>disp</code> method for the polynomial class might be
</p>
<div class="example">
<pre class="verbatim">function disp (p)

  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>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)
    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</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>
<span id="XREFsaveobj"></span><dl class="def">
<dt id="index-saveobj"><span class="category">: </span><span><em><var>b</var> =</em> <strong>saveobj</strong> <em>(<var>a</var>)</em><a href='#index-saveobj' class='copiable-anchor'> &para;</a></span></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>
<span id="XREFloadobj"></span><dl class="def">
<dt id="index-loadobj"><span class="category">: </span><span><em><var>b</var> =</em> <strong>loadobj</strong> <em>(<var>a</var>)</em><a href='#index-loadobj' class='copiable-anchor'> &para;</a></span></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>


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



</body>
</html>