Apifun  

Apifun

The goal of this module is to provide a set to function to check input arguments in macros.

Purpose

In functions with a variable number of input arguments, we often have the following source code, which checks that the number of input arguments provided by the user is consistent with the number of expected arguments :

[lhs,rhs]=argn(0)

if ( rhs < 2 | rhs > 5 ) then

errmsg = msprintf(gettext("%s: Unexpected number of input arguments : %d provided while from %d to %d are expected."), "myfunnction", rhs,2,5);

error(errmsg)

end

Writing this code is error-prone and boring.

For example, the apifun_checkrhs function checks that the number of input arguments provided by the user of the function corresponds to the number of expected arguments. The following function takes 2 or 3 input arguments and 1 output arguments.

function y = myfunction ( varargin )

[lhs, rhs] = argn()

apifun_checkrhs ( "myfunction" , rhs , 2:3 )

apifun_checklhs ( "myfunction" , lhs , 1 )

x1 = varargin(1)

x2 = varargin(2)

if ( rhs >= 3 ) then

x3 = varargin(3)

else

x3 = 2

end

y = x1 + x2 + x3

endfunction

When called with 1 or 4 arguments, an error will be generated.

The advantages of using the current module are the following.

  • Designing robust functions is much simpler which improves both the quality and the robustness of functions.
  • The provided source code is factored into one single mofule. Often, this code has been dispersed into many existing functions.
  • It is similar to what is provided to the developers of Scilab gateways, at the C level.
  • The localization issue is not a problem anymore: the number of messages to localize is reduced.

Features

The following is a list of the function currently implemented in this module:

  • apifun_overview — An overview of the Apifun toolbox.
  • apifun_checklhs — Generates an error if the number of LHS is not in given set.
  • apifun_checkrhs — Generates an error if the number of RHS is not in given set.

Support

  • apifun_argindefault — Returns the value of an input argument.
  • apifun_expandfromsize — Expand variables from a size.
  • apifun_expandvar — Expand variables so that they all have the same shape.
  • apifun_keyvaluepairs — Returns options from key-value pairs.

Check content

  • apifun_checkcomplex — Generates an error if the variable has a zero imaginary part.
  • apifun_checkflint — Generates an error if the variable is not a floating point integer.
  • apifun_checkgreq — Check that the value is greater or equal than a threshold.
  • apifun_checkloweq — Checks that the value is lower or equal than a threshold.
  • apifun_checkoption — Generates an error if the value of an input argument is not expected.
  • apifun_checkrange — Check that the value is in a given range.
  • apifun_checkreal — Generates an error if the variable has an imaginary part.

Check size

  • apifun_checkdims — Generates an error if the variable has not the required size.
  • apifun_checkscalar — Generates an error if the variable is not a scalar.
  • apifun_checksquare — Generates an error if the variable is not a square matrix.
  • apifun_checkveccol — Generates an error if the variable is not a column vector.
  • apifun_checkvecrow — Generates an error if the variable is not a row vector.
  • apifun_checkvector — Generates an error if the variable is not a vector.

Check type

  • apifun_checkcallable — Generates an error if the variable is not a callable function.
  • apifun_checktype — Generates an error if the given variable is not of expected type.

Forge

This project is managed on the Scilab Forge :

http://forge.scilab.org/index.php/p/apifun/

ATOMS

http://atoms.scilab.org/toolboxes/apifun

Author

  • Copyright (C) 2012 - 2013 - Michael Baudin
  • Copyright (C) 2010 - DIGITEO - Michael Baudin

Licence

This toolbox is released under the CeCILL_V2 licence :

http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt

Development Team
Admins
Allan Cornet
Vincent Couvert
Michael Baudin
Happy Crew
John Gliksberg

Powered by InDefero,
a Céondo Ltd initiative.