第三十一章 Caché 函數大全 $LISTGET 函數 <center> 第三十一章 Caché 函數大全 $LISTGET 函數 大綱 描述 參數 示例

<center> 第三十一章 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（正整數），則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