Checking for Parameters
The informational routines, N_ELEMENTS, SIZE, N_PARAMS, PARAM_PRESENT, and KEYWORD_SET, are useful in procedures and functions to check if arguments are supplied. Procedures should be written to check that all required arguments are supplied, and to supply reasonable default values for missing optional parameters.
Checking for Parameters
PARAM_PRESENT tests if a parameter was present in the call to a procedure or function. It returns a nonzero value (TRUE) if the specified parameter was present in the call to the current procedure or function. If the specified parameter is not present, this function returns zero, or FALSE.
PARAM_PRESENT complements the functions KEYWORD_SET and N_ELEMENTS, described later in this section. PARAM_PRESENT can distinguish between the different cases in which those two routines return FALSE. Examples of this use are shown in the following sections.
Checking for Keywords
The
KEYWORD_SET Function returns 1 (TRUE) if its parameter is defined and non-zero. The function returns 0 (FALSE) in the following cases:
1. When the keyword was set to zero.
2. When the keyword was not used in the call.
note | For keywords where 0 is a valid and meaningful value, do not use KEYWORD_SET to test the validity of the keyword. To test these keywords, use the N_ELEMENTS Function instead. |
For example, assume that a procedure is written which performs a computation and returns the result. If the keyword Plot is present and non-zero the procedure also plots its result:
; Procedure definition. Compute result.
PRO XYZ, result, Plot=Plot
; Plot result if keyword parameter is set.
IF KEYWORD_SET(Plot) THEN PLOT, result
END
A call to this procedure that produces a plot is:
xyz, r, /Plot
The PARAM_PRESENT function lets you distinguish between the two FALSE cases of KEYWORD_SET. It returns TRUE when the keyword is set to 0 and FALSE when the keyword was not used.
Checking for Number of Positional Parameters
The N_PARAMS function returns the number of positional parameters (not keyword parameters) present in a procedure or function call. A frequent use is to call N_PARAMS to determine if all arguments are present, and if not to supply default values for missing parameters. For example:
; Print values of xx and yy. If xx is omitted, print values of
; yy versus element number.
PRO XPRINT, xx, yy
; Check number of arguments.
CASE N_PARAMS() OF
; Single argument case.
1: BEGIN
; First argument is y values.
y = xx
; Create vector of subscript indices.
x = INDGEN(N_ELEMENTS(y))
END
; Two argument case. Copy parameters to local arguments.
2: BEGIN & y = yy & x = xx & END
; Wrong number of arguments.
ELSE: BEGIN
; Print message.
PRINT, 'XPRINT - Wrong number of arguments'
; Give up and return.
RETURN
END
ENDCASE
; Remainder of procedure.
...
END
Checking for Number of Elements
The N_ELEMENTS function returns the number of elements contained in any expression or variable. Scalars always have one element, even if they are scalar structures. The number of elements in arrays or vectors is equal to the product of the dimensions. The N_ELEMENTS function returns zero if its parameter is an undefined variable. The result is always a longword scalar.
For example, the following expression is equal to the mean of a numeric vector or array:
result = TOTAL(arr) / N_ELEMENTS(arr)
The N_ELEMENTS function provides a convenient method of determining if a variable is defined, as illustrated in the following statement. The following statement sets the variable abc to zero if it is undefined, otherwise the variable is not changed.
IF N_ELEMENTS(abc) EQ 0 THEN abc = 0
N_ELEMENTS is frequently used to check for omitted positional and keyword arguments. N_PARAMS can’t be used to check for the number of keyword parameters because it returns only the number of positional parameters. An example of using N_ELEMENTS to check for a keyword parameter is:
; Display an image with a given zoom factor. If Factor is omitted
; use 4.
PRO zoom, image, Factor=Factor
; Supply default for missing keyword.
IF N_ELEMENTS(Factor) EQ 0 THEN Factor = 4
If N_ELEMENTS is used to check for the number of keyword parameters, it returns 0 in the following cases:
1. When the keyword or parameter was present but is an undefined variable.
2. When the keyword or parameter was not present in the call.
The PARAM_PRESENT function lets you distinguish between the two cases when N_ELEMENTS returns zero (0). PARAM_PRESENT returns TRUE when the keyword was present by is an undefined variable. It returns FALSE when the keyword was not present in the call.
Checking for Size and Type of Parameters
The SIZE function returns a vector that contains information indicating the size and type of the parameter. The returned vector is always of type LONG. The first element is equal to the number of dimensions of the parameter, and is 0 if the parameter is a scalar. The following elements contain the size of each dimension. After the dimension sizes, the last two elements indicate the type of the parameter and the total number of elements respectively. The type is encoded as shown in
Table 11-4: Parameter Type Codes:
Example of Checking for Size and Type of Parameters
Assume A is an integer array with dimensions of (3, 4, 5). After executing, the statement:
B = SIZE(A)
assigns to the variable B a six-element vector containing:
A code segment that checks that a variable, A, is two-dimensional, and extracts the dimensions is:
; Get size vector.
s = SIZE(A)
; Two-dimensional?
IF s(0) NE 2 THEN BEGIN
; Print error message.
PRINT, 'Variable A is not two-dimensional'
; And exit.
RETURN
ENDIF
; Get number of columns and rows.
nx = s(1) & ny = s(2)
