Next: , Previous: Allocating Local Memory in Oct-Files, Up: Oct-Files


A.1.11 Input Parameter Checking in Oct-Files

As oct-files are compiled functions they have the possibility of causing Octave to abort abnormally. It is therefore important that each and every function has the minimum of parameter checking needed to ensure that Octave behaves well.

The minimum requirement, as previously discussed, is to check the number of input arguments before using them to avoid referencing a non existent argument. However, it some case this might not be sufficient as the underlying code imposes further constraints. For example an external function call might be undefined if the input arguments are not integers, or if one of the arguments is zero. Therefore, oct-files often need additional input parameter checking.

There are several functions within Octave that might be useful for the purposes of parameter checking. These include the methods of the octave_value class like is_real_matrix, etc, but equally include more specialized functions. Some of the more common ones are demonstrated in the following example

     /*
     
     Copyright (C) 2006, 2007 John W. Eaton
     
     This file is part of Octave.
     
     Octave is free software; you can redistribute it and/or 
     modify it under the terms of the GNU General Public License 
     as published by the Free Software Foundation; either
     version 3  of the License, or (at your option) any later 
     version.
     
     Octave is distributed in the hope that it will be useful, 
     but WITHOUT ANY WARRANTY; without even the implied warranty
     of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  
     See the GNU General Public License for more details.
     
     You should have received a copy of the GNU General Public 
     License along with Octave; see the file COPYING.  If not,
     see <http://www.gnu.org/licenses/>.
     
     */
     
     #include <octave/oct.h>
     
     DEFUN_DLD (paramdemo, args, nargout, 
     	   "Parameter Check Demo.")
     {
       int nargin = args.length ();
       octave_value retval;
     
       if (nargin != 1)
         print_usage();
       else if (nargout != 0)
         error ("paramdemo: function has no output arguments");
       else
         {
           NDArray m = args(0).array_value();
           double min_val = -10.0;
           double max_val = 10.0;
           octave_stdout << "Properties of input array:\n";
           if (m.any_element_is_negative ())
             octave_stdout << "  includes negative values\n";
           if (m.any_element_is_inf_or_nan())
             octave_stdout << "  includes Inf or NaN values\n";
           if (m.any_element_not_one_or_zero())
             octave_stdout << 
     	  "  includes other values than 1 and 0\n";
           if (m.all_elements_are_int_or_inf_or_nan())
             octave_stdout << 
     	  "  includes only int, Inf or NaN values\n";
           if (m.all_integers (min_val, max_val))
             octave_stdout << 
     	  "  includes only integers in [-10,10]\n";
         }
       return retval;
     }

and an example of its use is

     paramdemo ([1, 2, NaN, Inf])
      Properties of input array:
           includes Inf or NaN values
           includes other values than 1 and 0
           includes only int, Inf or NaN values