$LISTGET ($LG)
Synopsis
$LISTGET(list,position,default) $LG(list,position,default)
Parameters
| list | An expression that resolves to a Caché list. A Caché list is created using $LISTBUILD or $LISTFROMSTRING, or extracted from another list using $LIST. |
| position | Optional — An expression that resolves to a integer, specifying a position in list. Permitted values are -1, 0, and positive integers. |
| default | Optional — An expression that resolves to a value to return if the list element has an undefined value. |
Description
$LISTGET returns the requested element in the specified list. If the value of the position parameter refers to a nonexistent member or identifies an element with an undefined value, the specified default value is returned.
The $LISTGET function is identical to the one- and two-argument forms of the $LIST function except that, under conditions that would cause $LIST to produce a <NULL VALUE> error, $LISTGET returns a default value. See the description of the $LIST function for more information on conditions that generate <NULL VALUE> errors.
Parameters
position
The position parameter must evaluate to an integer. If it is omitted, by default, the function examines the first element of the list. If the value of the position parameter is -1, it is equivalent to specifying the last element of the list.
default
If you omit the default parameter, the null string ("") is assumed for the default value.
Examples
The $LISTGET functions in the following example both return “A”, the first element in the list:
list=$LISTBUILD("A","B","C")
PRINT $LISTGET(list)
PRINT $LISTGET(list,1)
The $LISTGET functions in the following example both return “C”, the third and last element in the list:
list=$LISTBUILD("A","B","C")
PRINT $LISTGET(list,3)
PRINT $LISTGET(list,-1)
The $LISTGET functions in the following example both return a value upon encountering the undefined 2nd element in the list. The first returns a question mark (?), which the user defined as the default value. The second returns a null string because a default value is not specified:
PRINT $LISTGET($LISTBUILD("A",,"C"),2,"?")
PRINT $LISTGET($LISTBUILD("A",,"C"),2)
The $LISTGET functions in the following example both specify a position greater than the last element in the three-element list. The first returns a null string because the default value is not specified. The second returns the user-specified default value, “ERR”:
list=$LISTBUILD("A","B","C")
PRINT $LISTGET(list,4)
PRINT $LISTGET(list,4,"ERR")
The $LISTGET functions in the following example both return a null string:
list=$LISTBUILD("A","B","C")
PRINT $LISTGET(list,0)
PRINT $LISTGET("")
Notes
Invalid Parameter Values
If the expression in the list parameter does not evaluate to a valid list, a <LIST> error can occur.
If the value of the position parameter is less than -1, invoking the $LISTGET function generates a <RANGE> error.
See Also
-
$LIST function
-
$LISTBUILD function
-
$LISTDATA function
-
$LISTFIND function
-
$LISTFROMSTRING function
-
$LISTLENGTH function
-
$LISTNEXT function
-
$LISTSAME function
-
$LISTTOSTRING function
-
$LISTVALID function
