$LISTDATA ($LD)
Synopsis
$LISTDATA(list,position) $LD(list,position)
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 an integer specifying a position in list. Valid values are -1, 0, and positive integers. |
Description
$LISTDATA checks for data in the requested element in a list and returns a boolean value. $LISTDATA returns a value of 1 if the element indicated by the position parameter is in the list and has a data value. $LISTDATA returns a value of a 0 if the element is not in the list or does not have a data value.
Parameters
list
A list is an encoded string containing multiple elements. A list must have been created using $LISTBUILD or $LISTFROMSTRING, or extracted from another list using $LIST.
position
If you omit the position parameter, $LISTDATA evaluates the first element. If the value of the position parameter is -1, it is equivalent to specifying the final element of the list. If the value of the position parameter refers to a nonexistent list member, then invoking the $LISTDATA function returns a 0.
Examples
The following examples show the results of the various values of the position parameter.
All of the following $LISTDATA statements return a value of 0 (Y is an undefined variable):
x=$LISTBUILD("Red",,Y,"","Green")
PRINT $LISTDATA(x,2); ! second element is undefined
PRINT $LISTDATA(x,3); ! third element is undefined variable
PRINT $LISTDATA(""); ! null string
PRINT $LISTDATA(x,0); ! the 0th position
PRINT $LISTDATA(x,6); ! 6th position in 5-element list
The following $LISTDATA statements return a value of 1 for the same five-element list:
x=$LISTBUILD("Red",,Y,"","Green")
PRINT $LISTDATA(x); ! first position (by default)
PRINT $LISTDATA(x,1); ! first position specified
PRINT $LISTDATA(x,4); ! fourth position value=null string
PRINT $LISTDATA(x,5); ! fifth position
PRINT $LISTDATA(x,-1); ! last (5th) position
Notes
Invalid Parameter Values
If the expression in the list parameter does not evaluate to a valid list, a <LIST> error occurs.
If the value of the position parameter is less than -1, invoking the $LISTDATA function generates a <RANGE> error.
See Also
-
$LIST function
-
$LISTBUILD function
-
$LISTFIND function
-
$LISTFROMSTRING function
-
$LISTGET function
-
$LISTLENGTH function
-
$LISTNEXT function
-
$LISTSAME function
-
$LISTTOSTRING function
-
$LISTVALID function
