Using Keyword Parameters

A short example of a function that exchanges two columns of a 4 x 4 homogeneous, coordinate-transformation matrix is shown below. The function has one positional parameter, the coordinate-transformation matrix T. The caller can specify one of the keywords XYEXCH, XZEXCH, or YZEXCH to interchange the xy, xz, or yz axes of the matrix. The result of the function is the new coordinate transformation matrix defined below.

; Function to swap columns of T. XYEXCH swaps columns 0 and 1,

; XZEXCH swaps 0 and 2, and YZEXCH swaps 1 and 2.

FUNCTION SWAP, T, XYEXCH = xy, XZEXCH = xz, YZEXCH = yz

 

   ; Swap columns 0 and 1 if keyword XYEXCH is set.

   IF KEYWORD_SET(XY) THEN S=[0,1] $

 

   ; Check to see if xz is set.

   ELSE IF KEYWORD_SET(XZ) THEN S=[0,2] $

 

   ; Check to see if yz is set.

   ELSE IF KEYWORD_SET(YZ) THEN S=[1,2] $

 

   ; If nothing is set, return.

   ELSE RETURN, T

 

   ; Copy matrix for result.

   R = T

 

; Exchange two columns using matrix insertion operators and

; subscript ranges.

   R[S[1], 0] = T[S[0], *]

   R[S[0], 0] = T[S[1], *]

 

   ; Return result.

   RETURN, R

 

END

Typical calls to SWAP are as follows:

Q = SWAP(!P.T, /XYEXCH)

Q = SWAP(Q, /XYEX)

Q = SWAP(INVERT(Z), YZ = 1)

Q = SWAP(Z, XYE = I EQ 0, XZE = I EQ 1, YZE = I EQ 2)

Note that keyword names can abbreviated to the shortest unambiguous string. The last example sets one of the three keywords according to the value of the variable I.

Note: Because keywords can be abbreviated, keywords within routines must have unique names that do not contain the name of another keyword from the same routine. For example, an error will result from using a keyword named mykeyword and another named mykeyword1.

Note: The only exception to the keyword abbreviation is the properties for the IDL Graphics functions. For these functions, the property names cannot be abbreviated. Instead, you must use the full property name.