Skip to main content

$LISTDATA ($LD)

Indicates whether the specified element exists and has a data value.

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

FeedbackOpens in a new tab