第二十八章 Caché 函数大全 $LISTDATA 函数

指示指定的元素是否存在并具有数据值。

大纲

$LISTDATA(list,position,var)
$LD(list,position,var)

参数

list 计算结果为有效列表的表达式。
position 可选—表达式，被解释为指定列表中的位置。正，非零整数或-1。
var 可选-包含在指定列表位置的元素值的变量。如果 $L I S T D A T A 返回值 1 ，则写入 v a r ；如果$ LISTDATA返回的值为0，则var保持不变。

描述

$LISTDATA在列表中的请求元素中检查数据，并返回一个布尔值。如果position参数指示的元素在列表中并且具有数据值，则$LISTDATA返回值1。如果该元素不在列表中或没有数据值，则$LISTDATA返回值为0。

（可选）$LISTDATA可以将元素值写入var变量。

注意：$LISTDATA不应在循环结构中用于返回多个连续的元素值。尽管这将起作用，但它的效率极低，因为$LISTDATA必须在每次迭代开始时就计算列表。 $LISTNEXT函数是返回多个连续元素值的更有效的方法。

参数

list

列表是包含多个元素的编码字符串。必须使用$LISTBUILD或$LISTFROMSTRING创建一个列表，或使用$LIST从另一个列表中提取一个列表。

可以使用$LISTVALID函数来确定表达式是否为有效列表。如果list参数中的表达式未求值为有效列表，则会发生<LIST> 错误。如果有效列表在指定位置不包含任何数据，则$LISTDATA返回0。

position

列表中元素的整数位置，从1开始计数。如果省略position参数，则$LISTDATA将计算第一个元素。如果position参数的值为-1，则等效于指定列表的最后一个元素。

如果position指向不存在的列表成员，则$LISTDATA返回0。位置0始终返回0。如果position的值小于-1，则调用$LISTDATA函数将产生<RANGE>错误。

var

如果$LISTDATA返回值1，则Caché将请求的元素的值写入var。如果$LISTDATA返回值0，则var不变。var参数可以是局部，全局或进程专用全局变量，带或不带下标。不需要定义；第一次返回1的$LISTDATA调用定义并设置了var。如果第一次调用$LISTDATA返回0，则var保持未定义状态。

var参数不能是非多维对象属性。尝试将值写入非多维对象属性会导致<OBJECT DISPATCH> 错误.

var参数不能为特殊变量。尝试将值写入特殊变量会导致错误。

示例

以下两个示例显示了position参数的各种值的结果。

以下$LISTDATA语句返回值0：

/// d ##class(PHA.TEST.Function).LISTDATA()
ClassMethod LISTDATA()
{
    
    
	KILL y
	SET x=$LISTBUILD("Red",,y,"","Green",)
	WRITE !,$LISTDATA(x,2)  ; 第二个元素未定义
	WRITE !,$LISTDATA(x,3)  ; 第三个元素是被杀死的变量
	WRITE !,$LISTDATA(x,-1) ; 最后一个元素未定义
	WRITE !,$LISTDATA(x,0)  ; 第0个位置
	WRITE !,$LISTDATA(x,6)  ; 5元素清单中的第六名
}

DHC-APP>d ##class(PHA.TEST.Function).LISTDATA()
 
0
0
0
0
0

以下$LISTDATA语句返回值1：

/// d ##class(PHA.TEST.Function).LISTDATA1()
ClassMethod LISTDATA1()
{
    
    
   SET x=$LISTBUILD("Red",,y,"","Green",)
   WRITE !,$LISTDATA(x)    ; 第一个元素（默认情况下）
   WRITE !,$LISTDATA(x,1)  ; 指定第一个元素
   WRITE !,$LISTDATA(x,4)  ; 第四个元素 ""字符串
   WRITE !,$LISTDATA(x,5)  ; 第五个元素
}

DHC-APP>d ##class(PHA.TEST.Function).LISTDATA1()
 
1
1
1
1

以下3参数$LISTDATA语句测试元素值的存在并使用该值更新evalue变量。请注意，当$LISTDATA返回0时，evalue保持不变：

/// d ##class(PHA.TEST.Function).LISTDATA2()
ClassMethod LISTDATA2()
{
    
    
	SET x=$LISTBUILD("Red",,y,"","Green",)
	FOR i=1:1:$LISTLENGTH(x) {
    
    
		WRITE "element ",i," data? ",$LISTDATA(x,i,evalue)," value ",evalue,! 
	}
	WRITE i," list elements"
}

DHC-APP>d ##class(PHA.TEST.Function).LISTDATA2()
element 1 data? 1 value Red
element 2 data? 0 value Red
element 3 data? 0 value Red
element 4 data? 1 value
element 5 data? 1 value Green
element 6 data? 0 value Green
6 list elements

以下所有$LISTDATA语句均返回值0：

/// d ##class(PHA.TEST.Function).LISTDATA3()
ClassMethod LISTDATA3()
{
    
    
	WRITE !,$LISTDATA($LB())             ; null list
	WRITE !,$LISTDATA($LB(UndefinedVar)) ; null list
	WRITE !,$LISTDATA("")        ; null string is a valid list but contain no data
	WRITE !,$LISTDATA($LB(,))    ; two-element null list
}

DHC-APP>d ##class(PHA.TEST.Function).LISTDATA3()
 
0
0
0
0

以下$LISTDATA语句返回值1：

/// d ##class(PHA.TEST.Function).LISTDATA4()
ClassMethod LISTDATA4()
{
    
    
  WRITE !,$LISTDATA($LB(""))       ; data is null string
  WRITE !,$LISTDATA($LB($CHAR(0))) ; data is non-display character
}

DHC-APP>d ##class(PHA.TEST.Function).LISTDATA4()
 
1
1