Using Keyword Parameters

A short example of a function that exchanges two columns of a 4 ´ 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.

This function example uses the system function KEYWORD_SET to determine if a keyword parameter has been passed and if it is nonzero. This is similar to using the condition:

IF N_ELEMENTS(P) NE 0 THEN IF P THEN ... ... 

to test if keywords that have a true/false value are both present and true.