文章目录

第三十一章 Caché 函数大全 $LISTGET 函数
大纲
- 参数
描述
参数
- list
- position
- default
示例

第三十一章 Caché 函数大全 $LISTGET 函数

返回列表中的元素，如果请求的元素未定义，则返回指定的默认值。

大纲

$LISTGET(list,position,default)
$LG(list,position,default)

参数

list 计算结果为有效列表的表达式。
position 可选—一个整数代码，用于指定列表中的起始位置。允许的值为n（从列表的开头算起），*（列表的最后一个元素）和* -n（从列表的末尾算起的相对偏移量）。因此，列表中的第一个元素为1，第二个元素为2，列表中的最后一个元素为*，倒数第二个元素为* -1。如果position是小数，则将其截断为整数部分。如果省略position，则默认为1。-1可以在较旧的代码中使用，以指定列表中的最后一个元素。弃用的-1不应与*或* -n相对偏移语法结合使用。
default 可选—一个表达式，提供如果list元素具有未定义值时要返回的值。如果省略默认值，则默认为空字符串（“”）。必须指定位置参数值才能指定默认值。

描述

$LISTGET返回指定列表中的请求元素。如果position的值引用了不存在的元素或标识了具有未定义值的元素，则返回默认值。

$LISTGET函数与$LIST函数的一参数形式和二参数形式相同，除了在可能导致$LIST产生<NULL VALUE>错误的条件下，$LISTGET返回一个默认值。

参数

list

可以使用$LISTBUILD或$LISTFROMSTRING创建列表，或使用$LIST从另一个列表中提取列表。空字符串（“”）也被视为有效列表。可以使用$LISTVALID来确定list是否为有效列表。无效的列表会导致$LISTGET生成错误。

position

要返回的列表元素的位置（元素计数）。元素以字符串形式返回。列表元素从1开始计数。如果省略position，则$LISTGET返回第一个元素。

如果position为n（正整数），则 $L I S T G E T 从列表的开头开始计数元素。如果 p o s i t i o n 大于 l i s t 中的元素数，则$ LISTGET返回默认值。
如果position为*，则$LIST返回列表中的最后一个元素。
如果position为* -n（星号后跟一个负整数），则$LIST通过相对于列表末尾的相对偏移量来计数元素。因此，*-0是列表中的最后一个元素，*-1是倒数第二个列表元素（从末尾偏移1）。如果* -n偏移量指定列表的第一个元素之前的位置（例如，对于3元素的列表，则为* -3），则$LISTGET返回默认值。如果* -n偏移量指定了一个在其之前的位置（例如，对于3元素列表，则为* -4），则Caché会发出 <RANGE> 错误。
如果position为0或-0，则$LISTGET返回默认值。

position参数的数字部分计算为整数。 Caché将一个小数部分截断为其整数部分。将位置指定为-1（指示列表的最后一个元素）已被弃用，不应在新代码中使用；小于-1的位置负数会产生错误。

使用变量指定* -n时，必须始终在参数本身中指定星号和符号字符。

以下是* -n的有效规格：

/// d ##class(PHA.TEST.Function).LISTGET()
ClassMethod LISTGET()
{
    
    
	SET count=2
	SET alph=$LISTBUILD("a","b","c","d")
	WRITE $LISTGET(alph,*-count,"blank")
}

DHC-APP>d ##class(PHA.TEST.Function).LISTGET()
b

/// d ##class(PHA.TEST.Function).LISTGET1()
ClassMethod LISTGET1()
{
    
    
	SET count=-2
	SET alph=$LISTBUILD("a","b","c","d")
	WRITE $LISTGET(alph,*+count,"blank")
}

DHC-APP>d ##class(PHA.TEST.Function).LISTGET1()
b

default

计算结果为字符串或数字值的表达式。如果由position指定的元素不存在，则$LISTGET返回默认值。如果position超出列表的末尾，position指定的元素没有值，position为0或list不包含任何元素，则可能发生这种情况。但是，如果位置* -n指定列表的第0个元素之前的位置，则Caché会发出 <RANGE> 错误。

示例

以下示例中的$LISTGET函数返回由position指定的列表元素的值（位置的默认值为1）：

/// d ##class(PHA.TEST.Function).LISTGET2()
ClassMethod LISTGET2()
{
    
    
	SET list=$LISTBUILD("A","B","C")
	WRITE !,$LISTGET(list)     ; returns "A"
	WRITE !,$LISTGET(list,1)   ; returns "A"
	WRITE !,$LISTGET(list,3)   ; returns "C"
	WRITE !,$LISTGET(list,*)   ; returns "C"
	WRITE !,$LISTGET(list,*-1) ; returns "B"
}

DHC-APP>d ##class(PHA.TEST.Function).LISTGET2()
 
A
A
C
C
B

以下示例中的$LISTGET函数在遇到列表中未定义的第二个元素时返回一个值。前两个返回问号（？），用户已将其定义为默认值。后两个返回空字符串，因为用户尚未指定默认值：

/// d ##class(PHA.TEST.Function).LISTGET3()
ClassMethod LISTGET3()
{
    
    
	WRITE "returns:",$LISTGET($LISTBUILD("A",,"C"),2,"?"),!
	WRITE "returns:",$LISTGET($LISTBUILD("A",,"C"),*-1,"?"),!
	WRITE "returns:",$LISTGET($LISTBUILD("A",,"C"),2),!
	WRITE "returns:",$LISTGET($LISTBUILD("A",,"C"),*-1)
}

DHC-APP>d ##class(PHA.TEST.Function).LISTGET3()
returns:?
returns:?
returns:
returns:

以下示例返回列表中的所有元素值。它还列出了列表结尾之前和之后的位置。如果不存在值，则返回默认值：

/// d ##class(PHA.TEST.Function).LISTGET4()
ClassMethod LISTGET4()
{
    
    
	SET list=$LISTBUILD("a","b",,"d",,,"g")
	SET llen=$LISTLENGTH(list)
	FOR x=0:1:llen+1 {
    
     
		WRITE "位置 ",x,"=",$LISTGET(list,x," no value"),!
	}
	WRITE "列表结束"
}

DHC-APP>d ##class(PHA.TEST.Function).LISTGET4()
位置 0= no value
位置 1=a
位置 2=b
位置 3= no value
位置 4=d
位置 5= no value
位置 6= no value
位置 7=g
位置 8= no value
列表结束

以下示例以相反的顺序返回列表中的所有元素值。在省略值的情况下，它将返回默认值：

/// d ##class(PHA.TEST.Function).LISTGET5()
ClassMethod LISTGET5()
{
    
    
	SET list=$LISTBUILD("a","b",,"d",,,"g")
	SET llen=$LISTLENGTH(list)
	FOR x=0:1:llen {
    
     
		WRITE "位置 *-",x,"=",$LISTGET(list,*-x," no value"),!
	}
	WRITE "列表结束"
}

DHC-APP>d ##class(PHA.TEST.Function).LISTGET5()
位置 *-0=g
位置 *-1= no value
位置 *-2= no value
位置 *-3=d
位置 *-4= no value
位置 *-5=b
位置 *-6=a
位置 *-7= no value
列表结束

以下示例中的$LISTGET函数返回空字符串的list元素值；它们不返回默认值：

/// d ##class(PHA.TEST.Function).LISTGET6()
ClassMethod LISTGET6()
{
    
    
	WRITE "returns:",$LISTGET($LB(""),1,"no value"),!
	WRITE "returns:",$LISTGET($LB(""),*,"no value"),!
	WRITE "returns:",$LISTGET($LB(""),*-0,"no value")
}

DHC-APP>d ##class(PHA.TEST.Function).LISTGET6()
returns:
returns:
returns:

以下示例中的$LISTGET函数均返回默认值：

/// d ##class(PHA.TEST.Function).LISTGET7()
ClassMethod LISTGET7()
{
    
    
	WRITE $LISTGET("",1,"no value"),!
	WRITE $LISTGET($LB(),1,"no value"),!
	WRITE $LISTGET($LB(UndefinedVar),1,"no value"),!
	WRITE $LISTGET($LB(,),1,"no value"),!
	WRITE $LISTGET($LB(,),*,"no value"),!
	WRITE $LISTGET($LB(,),*-1,"no value"),!
	WRITE $LISTGET($LB(""),2,"no value"),!
	WRITE $LISTGET($LB(""),*-1,"no value")
}

DHC-APP>d ##class(PHA.TEST.Function).LISTGET7()
no value
no value
no value
no value
no value
no value
no value
no value