第三十一章 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中的元素數，則 LISTGET從列表的開頭開始計數元素，如果position大于list中的元素數，則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