8.8.6. Parameters - Validation#

If a default-parameter (or let’s say template) is given in form of an instance of class ito::Param and a new value in terms of an instance of class ito::ParamBase is given, you might be interested if the new value fits to the type and the optional restrictions given by meta information of the template.

Therefore, the class ParamHelper (folder helper) provide method to validate ParamBase-instances with respect to a given meta information struct or to compare the compatibility of two different parameters.

Note

Since ParamHelper is not directly available for plugins, the most important methods are also made available by the API functions (see itom API). Therefore the API-call for the validator functions is also indicated below.

8.8.6.1. Validation with respect to given meta information#

If you have access to any meta information instance (derived from class ParamMeta), you can check whether the value of an instance of class ParamBase or its derived class Param fits to the given requirements. There are different validator functions depending on the type of meta information.

static ito::RetVal validateCharMeta(const ito::CharMeta *meta, double value)

This methods checks whether the number ‘value’ does not exceed the boundaries given by the char meta information ‘meta’. If this is not the case retError with an appropriate error message is returned, else retOk.

API-Call: ito::RetVal apiValidateCharMeta (const ito::CharMeta *meta, double value)

static ito::RetVal validateIntMeta(const ito::IntMeta *meta, int value)

This methods checks whether the number ‘value’ does not exceed the boundaries given by the integer meta information ‘meta’. If this is not the case retError with an appropriate error message is returned, else retOk.

API-Call: ito::RetVal apiValidateIntMeta (const ito::IntMeta *meta, int value)

static ito::RetVal validateDoubleMeta(const ito::DoubleMeta *meta, double value)

API-Call: ito::RetVal apiValidateDoubleMeta (const ito::DoubleMeta *meta, double value)

static ito::RetVal validateDoubleMetaAndRoundToStepSize(const ito::DoubleMeta *meta, double &value, bool allowRounding = true)

This methods checks whether the number ‘value’ does not exceed the boundaries given by the double meta information ‘meta’. If this is not the case retError with an appropriate error message is returned, else retOk. In difference to validateDoubleMeta(), this method rounds the given value to the nearest value, that fits to the step size constraints (if a step size != 0.0 is given).

The rounding is only done, if allowRounding is equal to true, else value will not be modified and can be considered to be constant.

API-Call: Right now, there is no direct API-function for this function, however validateAndCastParam() uses this function for double-based parameters.

static ito::RetVal validateDoubleMetaAndRoundToStepSize(const ito::DoubleMeta *meta, ito::ParamBase &doubleParam, bool allowRounding = true): This method is equal to the method described above. The single difference is that the value to test is not passed as single double value but as parameter that must have the type ito::ParamBase::Double.

static ito::RetVal validateStringMeta(const ito::StringMeta *meta, const char* value, bool mandatory = false)

This methods checks whether the string, passed by argument value, fits to the requirements of the string meta information meta. If it does not fit, retError is returned with an appropriate error message. If argument mandatory is false, retOk is also returned if the string is not given, hence, value is an empty string.

API-Call: ito::RetVal apiValidateStringMeta (const ito::StringMeta meta, const char value, bool mandatory = false)

static ito::RetVal validateHWMeta(const ito::HWMeta *meta, ito::AddInBase *value, bool mandatory = false)

This method checks whether the plugin given by ‘value’ fits to the requirements possibly defined in the ‘meta’-plugin meta information struct. If this is the case retOk is returned, else retError with an appropriate error message. If ‘value’ is NULL retOk is only returned if argument ‘mandatory’ is false.

API-Call: ito::RetVal apiValidateHWMeta (const ito::HWMeta *meta, ito::AddInBase *value, bool mandatory = false)

static ito::RetVal validateCharArrayMeta(const ito::ParamMeta *meta, const char* values, size_t len)

This methods checks whether the array of character values named ‘values’ (length ‘len’) fits to the requirements given by the meta information of meta. This can be both restrictions with respect to every single values as well as the length of the array. If this is not the case retError with an appropriate error message is returned, else retOk.

API-Call: ito::RetVal apiValidateCharArrayMeta (const ito::ParamMeta meta, const char values, size_t len)

static ito::RetVal validateIntArrayMeta(const ito::ParamMeta *meta, const int* values, size_t len)

This methods checks whether the array of integer values named ‘values’ (length ‘len’) fits to the requirements given by the meta information of meta. This can be both restrictions with respect to every single values as well as the length of the array. If this is not the case retError with an appropriate error message is returned, else retOk.

If the meta information indicates that an interval, range or rectangle is expected, the specific validations and tests are done, too.

API-Call: ito::RetVal apiValidateIntArrayMeta (const ito::ParamMeta meta, const int values, size_t len)

static ito::RetVal validateDoubleArrayMeta(const ito::ParamMeta *meta, const double* values, size_t len)

This methods checks whether the array of double values named ‘values’ (length ‘len’) fits to the requirements given by the meta information of meta. This can be both restrictions with respect to every single values as well as the length of the array. If this is not the case retError with an appropriate error message is returned, else retOk.

If the meta information indicates that an interval is expected, the specific validations and tests are done, too.

API-Call: ito::RetVal apiValidateDoubleArrayMeta (const ito::ParamMeta meta, const double values, size_t len)

8.8.6.2. Overall validation methods#

The following functions are overall functions that use the methods described above, depending on the type of the given template and parameter.

static ito::RetVal validateParam(const ito::Param &templateParam, const ito::ParamBase &param, bool strict = true, bool mandatory = false)

This method uses the methods above to check whether the value of ‘param’ is valid with respect to the type and meta information of ‘templateParam’. If ‘strict’ is false, the type is tried to be converted to type of ‘templateParam’ if possible. The ‘mandatory’ parameter is redirected to the corresponding validation methods above as therefore has the same meaning.

API-Call: ito::RetVal **apiValidateParam**(-same arguments-)

static ito::RetVal validateAndCastParam(const ito::Param &templateParam, ito::ParamBase &param, bool strict = true, bool mandatory = false, bool roundToSteps = false)

The difference to validateParam() is that the given argument param can be changed to the same type than templateParam if they can be cast and if it is a double value, its real value can be adapted to fit any step size constraints (only if roundToSteps = true).

API-Call: ito::RetVal apiValidateAndCastParam (-same arguments-)