Source code: prits_tools__parcheck.pro

Class: PRITS_TOOLS

Description

Routine to check user parameters to a procedure or function.

This routine checks whether a parameter fulfills some criteria. It checks the data type and the number of dimensions. Optionally, it can also check for minimum and/or maximum allowed values, or for object and structure names. If the parameter is undefined, then the DEFAULT value is returned if provided. If one of the tests fails a message is printed and a RETALL issued. These consequences can be suppressed by supplying the RESULT keyword.

Syntax

prits_tools.parcheck, parameter, parnum, name, types, valid_ndims [, default=default] [, maxval=maxval] [, minval=minval] [, valid_nelements=valid_nelements] [, /optional] [, structure_name=structure_name] [, object_name=object_name] [, disallow_subclasses] [, result=result]

Arguments

PARAMETER

Parameter passed to the routine.

PARNUM

Integer parameter number. This information will be used in a possible error message. If set to zero the parameter is assumed to be a keyword.

NAME

The name of the parameter. This information will be used in a possible error message.

TYPES

Integer or string, scalar or vector of valid types:

• 0 = undefined
• 1 = byte ; 2 = int ; 3 = long
• 4 = float ; 5 = double ; 6 = complex
• 7 = string ; 8 = struct ; 9 = dcomplex
• 12 = uint ; 13 = ulong ; 14 = long64
• 15 = ulong64
• 10 = pointer
• 11 = objref (any object, including 'list', 'hash', 'dictionary' and 'orderedhash')

Additional valid string types, which signify a collection of valid types: (in paranthesis are the valid type numbers that are included)

• unsigned (1, 12, 13, 15)
• signed (2, 3, 14)
• integers (unsigned + signed = 1, 2, 3, 12, 13, 14, 15)
• floats (4, 5)
• numeric (integers + floats = 1, 2, 3, 4, 5, 12, 13, 14, 15)
• multiplicative (numeric + 6, 9 = 1, 2, 3, 4, 5, 6, 9, 12, 13, 14, 15)

Even more valid string types:

• time (checks if input has a valid time format, calls 'valid_time')
• time0 (same as 'time' but zero is a valid time)

VALID_NDIMS

Integer, scalar or vector, giving number of allowed dimensions. For scalar values, the number of dimensions is zero.

Optional Input

DEFAULT

If parameter is undefined, then DEFAULT will be returned.

MINVAL

Minimum value for the parameter. Checked against MIN([parameter]).

MAXVAL

Maximum value for the parameter. Checked against MAX([parameter]).

VALID_NELEMENTS

Number, scalar or 2-element vector. Checks whether the input parameter has the exact number of elements, or, if VALID_NELEMENT is a 2-element vector, is within a range of number of elements. If the first element of VALID_NELEMENTS is zero, then this implies that UNDEFINED parameters are allowed.

STRUCTURE_NAME

String, scalar or vector. If the input parameter is of type 8 (STRUCT), the name of the structure is checked against STRUCTURE_NAME.

OBJECT_NAME

String, scalar or vector. If the input parameter is of type 11 (OBJREF), the name of the object is checked against OBJECT_NAME, objects inheriting from the given OBJECT_NAME are also allowed by default, except if DISALLOW_SUBCLASSES keyword is set.

Optional Output

RESULT

Receives the error messages (string array). If present, no error message is printed out and procedure returns to caller without stopping.

Keywords

OPTIONAL

If set, then parameter is optional, i.e. it can also be UNDEFINED, same as adding UNDEFINED to TYPES, or setting first element of VALID_NELEMENTS to zero, or providing a default.

DISALLOW_SUBCLASSES

If set, then objects inheriting from given OBJECT_NAME are not allowed.

Restrictions

LIST, HASH, DICTIONARY and ORDEREDHASH always have dimension 1, except if they are empty. A 1-dimensional array of those will also have dimension 1.

Side effects

If an error in the parameter is found, an error message is printed and an exception issued, except if the keyword RESULT is present. In that case RESULT will contain the error message, and no exception is thrown.