<< apifun_expandvar Support Check content >>

Apifun >> Apifun > Support > apifun_keyvaluepairs

apifun_keyvaluepairs

Returns options from key-value pairs.

Calling Sequence

options=apifun_keyvaluepairs(default)
options=apifun_keyvaluepairs(default,key1,value1)
options=apifun_keyvaluepairs(default,key1,value1,key2,value2,...)

Parameters

default :

a struct, the default values of the options

key1 :

a 1-by-1 matrix of strings, the name of the first option

value1 :

the value of the first option

options :

a struct, the actual values of the options

Description

The function manages a set of options identified by their keys. The key-value pairs are processed by replacing any actual option by its actual value. This function is designed to be used within functions having optional arguments.

The default input argument must contain the default values of the arguments. Its fields define the set of valid options.

The calling sequence options=apifun_keyvaluepairs (default) returns options as a copy of default.

The calling sequence options=apifun_keyvaluepairs (default,key1,value1) first checks that key1 is a valid key, by comparing it to the list of fields of the default data structure. If the field is unknown, an error is generated. If the field is valid, the associated field of options is set to value1.

The value1 variable can have any valid data type. There is no check that value1 has the same type as the associated field in default: the check of the type is left to the user of apifun_keyvaluepairs.

The other key-value pairs are treated in the same way.

Examples

// A theoretical use-case
//
// Set the defaults
default.a = 1;
default.b = 1;
default.c = 1;
options=apifun_keyvaluepairs (default)
options=apifun_keyvaluepairs (default,"a",2)
options=apifun_keyvaluepairs (default,"b",12)
options=apifun_keyvaluepairs (default,"b",12,"a",999)
options=apifun_keyvaluepairs (default,"c",-1,"b",12,"a",999)
// Error cases:
options=apifun_keyvaluepairs (default,"c")
options=apifun_keyvaluepairs (default,"d",2)

// A practical use-case: a function with 3 optional arguments.
// y = myfunction(x)
// y = myfunction(x,key1,value1,...)
// Available keys:
// "a" (default a=1)
// "b" (default b=1)
// "c" (default c=1)
function y=myfunction(x, varargin)
//
// 1. Set the defaults
default.a = 1
default.b = 1
default.c = 1
//
// 2. Manage (key,value) pairs
options=apifun_keyvaluepairs (default,varargin(1:$))
//
// 3. Get parameters
a = options.a
b = options.b
c = options.c
// TODO : check the types, size and content of a, b, c
y = a*x^2+b*x+c
endfunction
//
y = myfunction(1)
expected = 1*1^2+1*1+1
//
y = myfunction(1,"a",2)
expected = 2*1^2+1*1+1
//
y = myfunction(1,"b",3)
expected = 1*1^2+3*1+1
//
y = myfunction(1,"c",4,"b",3)
expected = 1*1^2+3*1+4
//
// Error cases:
y = myfunction(1,"d")
y = myfunction(1,"d",4)

Authors

Bibliography

"Why using key=value syntax to manage input arguments is not a good idea", Michael Baudin, 2011, http://wiki.scilab.org/


<< apifun_expandvar Support Check content >>