第二十七章 Caché 函數大全 $LISTBUILD 函數 第二十七章 Caché 函數大全 $LISTBUILD 函數 大綱 描述 示例

第二十七章 Caché 函數大全 $LISTBUILD 函數

根據指定的表達式構建元素列表。

大綱

$LISTBUILD(element,...) 
$LB(element,...)

SET $LISTBUILD(var1,var2,...)=list
SET $LB(var1,var2,...)=list

參數

• element 一個指定列表元素值的表達式。可以是單個表達式，也可以是逗號分隔的表達式列表中的一個表達式。可以爲省略的元素指定一個佔位符逗號。
• var 一個變量，指定爲單個變量或以逗號分隔的變量列表中的變量。可以爲省略的變量指定一個佔位符逗號。 var可以是任何類型的變量：局部變量，進程私有變量或全局變量，未下標或下標。
• list 計算結果爲有效列表的表達式。由於列表包含編碼，因此必須使用$LISTBUILD或$LISTFROMSTRING創建列表，或者使用$LIST從另一個列表中提取列表。

描述

$LISTBUILD有兩種語法形式：$LISTBUILD和SET $LISTBUILD：

• $LISTBUILD（element1，element2，...）接受一個或多個表達式，併爲每個表達式返回一個包含一個元素的編碼列表結構。元素以指定的順序放置在列表中。元素從1開始計數。
• SET $LISTBUILD（var1，var2，...）= list將列表中的多個元素提取到變量中。 list的每個元素都將複製到var變量中，該變量與其在$LISTBUILD參數列表中的位置相對應。

$LISTBUILD(element1,element2,...)

$LISTBUILD接受一個或多個表達式，併爲每個表達式返回一個包含一個元素的編碼列表結構。元素以指定的順序放置在列表中。元素從1開始計數。

以下功能可用於創建列表：

• $LISTBUILD，它從多個數據項（字符串或數字）創建一個列表，每個數據項一個列表元素。 $LISTBUILD也可用於創建不包含數據的列表元素。
• $LISTFROMSTRING，它從包含多個定界元素的單個字符串創建列表。
• $LIST，從現有列表中提取子列表。
• 空字符串（“”）也被視爲有效列表。空字符串（“”）用於表示一個空列表，該列表不包含任何元素。因爲它不包含列表元素，所以$LISTLENGTH（“”）返回的元素計數爲0。
• 某些$CHAR非打印字符組合，例如$CHAR（1），$CHAR（2,1）和$CHAR（3,1，asciicode）也可以返回已編碼的空列表或單元素列表。

可以使用$LISTVALID函數來確定表達式是否爲有效列表。

$LISTBUILD與其他$LIST函數一起使用：$LISTDATA，$LISTFIND，$LISTGET，$LISTNEXT，$LISTLENGTH，$LISTSAME和$LISTTOSTRING。

如果列表元素中的一個或多個字符是寬字符（Unicode），則該元素中的所有字符均表示爲寬字符。爲了確保系統之間的兼容性，無論硬件平臺如何，$LISTBUILD始終以相同的方式存儲這些字節。寬字符表示爲字節字符串。

注意：$LISTBUILD和其他$LIST函數使用優化的二進制表示形式來存儲數據元素。因此，當比較編碼列表時，等效測試可能無法按預期工作。在其他情況下，可能被視爲等效的數據可能具有不同的內部表示形式。例如，$LISTBUILD（1）不等於$LISTBUILD（“1”），$LISTBUILD（1.0）不等於$LISTBUILD（1）。但是，列表顯示功能（例如$LIST和$LISTTOSTRING）以規範形式返回數字列表元素值。因此，$LIST（$LISTBUILD（1），1）= $LIST（$LISTBUILD（“ 1”），1）。

出於相同的原因，在使用定界符的字符搜索和解析函數（例如$PIECE和$LENGTH的兩個參數形式）中，不應使用$LISTBUILD返回的編碼列表值。 $LISTBUILD創建的列表中的元素沒有用字符定界符標記，因此可以包含任何字符。

SET $LISTBUILD

當在SET命令中等號的左側使用時，$LISTBUILD函數將從列表中提取多個元素作爲單個操作。語法如下：

SET $LISTBUILD(var1,var2,...)=list

$LISTBUILD的var參數是用逗號分隔的變量列表，每個變量都接收與其在$LISTBUILD參數列表中的位置相對應的list元素。 var參數不必是現有變量；在SET $LISTBUILD爲其分配值時定義該變量。

• var參數的數量可以小於或大於列表元素的數量。未指定的var值保留其先前值；如果以前未定義，則它們保持未定義。多餘的列表元素將被忽略。
• var參數和/或list元素可以包含省略的值，以佔位符逗號表示。省略的var參數是未定義的。省略列表元素會導致相應的var值保留其先前值；如果以前未定義，則保持未定義。

SET $LISTBUILD是一個原子操作。 var參數的最大數量爲128。嘗試超過此數量將導致<SYNTAX>錯誤。

如果var參數是對象屬性（object.property），則該屬性必須是多維的。任何屬性都可以在對象方法中引用爲i％property實例變量。

在以下示例中，$LISTBUILD（在等號右側）創建一個包含四個元素的列表。

在以下示例中，SET $LISTBUILD將列表中的前兩個元素提取爲兩個變量：

/// d ##class(PHA.TEST.Function).LISTBUILD()
ClassMethod LISTBUILD()
{
   SET colorlist=$LISTBUILD("red","blue","green","white")
   SET $LISTBUILD(a,b)=colorlist
   WRITE "a=",a," b=",b   /* a="red" b="blue" */
}

DHC-APP>d ##class(PHA.TEST.Function).LISTBUILD()
a=red b=blue

在以下示例中，SET $LISTBUILD將列表中的元素提取爲五個變量。由於指定的列表沒有第5個元素，因此相應的var變量（e）包含其先前值：

/// d ##class(PHA.TEST.Function).LISTBUILD1()
ClassMethod LISTBUILD1()
{
    SET (a,b,c,d,e)=0
    SET colorlist=$LISTBUILD("red","blue","green","white")
    SET $LISTBUILD(a,b,c,d,e)=colorlist
    WRITE "a=",a," b=",b," c=",c," d=",d," e=",e
    /* a="red" b="blue" c="green" d="white" e=0 */
}

DHC-APP>d ##class(PHA.TEST.Function).LISTBUILD1()
a=red b=blue c=green d=white e=0

在下面的示例中，SET $LISTBUILD將列表中的元素提取爲四個變量。由於指定的列表沒有第三個元素，因此相應的var變量（c）包含其先前值：

/// d ##class(PHA.TEST.Function).LISTBUILD2()
ClassMethod LISTBUILD2()
{
    SET (a,b,c,d)=0
    SET colorlist=$LISTBUILD("red","blue",,"white")
    SET $LISTBUILD(a,b,c,d)=colorlist
    WRITE "a=",a," b=",b," c=",c," d=",d
    /* a="red" b="blue" c=0 d="white" */
}

DHC-APP>d ##class(PHA.TEST.Function).LISTBUILD2()
a=red b=blue c=0 d=white

在下面的示例中，SET $LISTBUILD將列表中的元素提取爲四個變量。由於第三個列表元素值是嵌套列表，因此相應的var變量（c）包含一個列表值：

/// d ##class(PHA.TEST.Function).LISTBUILD3()
ClassMethod LISTBUILD3()
{
    SET (a,b,c,d)=0
    SET colorlist=$LISTBUILD("red","blue",$LISTBUILD("green","yellow"),"white")
    SET $LISTBUILD(a,b,c,d)=colorlist
    WRITE "a=",a," b=",b," c=",c," d=",d
    /* a="red" b="blue" c=$LB("green","yellow") d="white" */
}

DHC-APP>d ##class(PHA.TEST.Function).LISTBUILD3()
a=red b=blue c=greeyellow d=white

示例

這裏顯示的許多示例都使用``LISTBUILD返回值以進行顯示。$LISTBUILD`返回無法直接顯示的編碼字符串。

DHC-APP> SET colorlist=$LISTBUILD("Red","Blue","Green")
 
DHC-APP>WRITE $LISTTOSTRING(colorlist,"^")
Red^Blue^Green

下面的示例創建六個數字元素的列表，這些列表顯示爲“3^0^44^5.6^33^400”。請注意，$LISTBUILD基於優化的二進制表示形式對數字元素值進行編碼，這可能與規範形式不同。列表顯示功能（例如$LIST和$LISTTOSTRING）以規範形式返回數字元素值：

DHC-APP>SET numlist=$LISTBUILD(003,0.00,44.0000000,5.6,+33,4E2)
 
DHC-APP>WRITE $LISTTOSTRING(numlist,"^")
3^0^44^5.6^33^400

省略元素

省略元素表達式定義了一個編碼元素，但是該元素的數據值未定義。

在下面的示例中，$LISTBUILD語句均生成一個有效的三元素列表，其第二個元素具有未定義的值。省略元素併爲元素指定未定義的變量會產生完全相同的結果。在任何一種情況下，使用任何列表函數（例如$LIST或$LISTTOSTRING）引用第二個元素都會產生錯誤：

/// d ##class(PHA.TEST.Function).LISTBUILD4()
ClassMethod LISTBUILD4()
{
    KILL a
    SET list1=$LISTBUILD("Red",,"Green")
    SET list2=$LISTBUILD("Red",a,"Green")
    WRITE "List lengths:",$LISTLENGTH(list1)," ",$LISTLENGTH(list2),!
    IF $LISTVALID(list1)=1,$LISTVALID(list2)=1 {
        WRITE "有效 lists",! 
    }
    IF list1=list2 {
        WRITE "list相同"
    } ELSE {
        WRITE "list不相同"
    }
}

DHC-APP>d ##class(PHA.TEST.Function).LISTBUILD4()
List lengths:3 3
有效 lists
list相同

以下示例顯示可以在列表末尾以及列表內指定未定義的元素。帶有尾部未定義元素的列表是有效列表。但是，使用任何列表函數引用此未定義元素都會產生<NULL VALUE>錯誤：

/// d ##class(PHA.TEST.Function).LISTBUILD5()
ClassMethod LISTBUILD5()
{
    KILL z
    SET list3=$LISTBUILD("Red",)
    SET list4=$LISTBUILD("Red",z)
    WRITE "List lengths:",$LISTLENGTH(list3)," ",$LISTLENGTH(list4),!
    IF $LISTVALID(list3)=1,$LISTVALID(list4)=1 {
        WRITE "有效 lists",! 
    }
    IF list3=list4 {
        WRITE "list相同"
    } ELSE {
        WRITE "list不相同"
    }
}

DHC-APP>d ##class(PHA.TEST.Function).LISTBUILD5()
List lengths:2 2
有效 lists
list相同

但是，以下示例將生成一個三元素列表，其第二個元素具有數據值：空字符串。引用第二個元素時，不會發生錯誤情況：

/// d ##class(PHA.TEST.Function).LISTBUILD6()
ClassMethod LISTBUILD6()
{
    SET list5=$LISTBUILD("Red","","Green")
    SET list5len=$LISTLENGTH(list5)
    WRITE "List length: ",list5len,!
    FOR i=1:1:list5len {
        WRITE "Element ",i," value: ",$LIST(list5,i),! 
    }
}

DHC-APP>d ##class(PHA.TEST.Function).LISTBUILD6()
List length: 3
Element 1 value: Red
Element 2 value:
Element 3 value: Green
 

沒有數據或NULL空字符串數據的列表

使用$LISTBUILD創建的任何列表都至少包含一個編碼列表元素。該元素可能包含或可能不包含數據。因爲$LISTLENGTH是元素而不是數據，所以使用$LISTBUILD創建的任何列表的列表長度至少爲1。

引用其數據值未定義的$LISTBUILD元素會生成錯誤。以下是創建“空”列表的所有有效$LISTBUILD語句。但是，嘗試引用元素是這樣的列表會導致<NULL VALUE>錯誤：

/// d ##class(PHA.TEST.Function).LISTBUILD7()
ClassMethod LISTBUILD7()
{
    TRY {
        SET x=$LISTBUILD(UndefinedVar)
        SET y=$LISTBUILD(,)
        SET z=$LISTBUILD()
        IF $LISTVALID(x)=1,$LISTVALID(y)=1,$LISTVALID(z)=1 {
            WRITE "無效 lists",! 
        }
        WRITE "$LB(UndefinedVar) contains ",$LISTLENGTH(x)," elements",!
        WRITE "$LB(,) contains ",$LISTLENGTH(y)," elements",!
        WRITE "$LB() contains ",$LISTLENGTH(z)," elements",!
        /* 使用null list */
        WRITE "$LB(UndefinedVar) list value ",$LISTTOSTRING(x,"^"),!
        WRITE "$LB(,) list value ",$LISTTOSTRING(y,"^"),!
        WRITE "$LB() list value ",$LISTTOSTRING(z,"^"),!
    }
    CATCH exp { WRITE !!,"在Cactch塊",!
        IF 1=exp.%IsA("%Exception.SystemException") {
            WRITE "System exception",!
            WRITE "Name: ",$ZCVT(exp.Name,"O","HTML"),!
            WRITE "Location: ",exp.Location,!
            WRITE "Code: "
        } ELSE { 
            WRITE "其他異常",! RETURN 
        }
        WRITE exp.Code,!
        WRITE "Data: ",exp.Data,! 
        RETURN
    }
}

DHC-APP>d ##class(PHA.TEST.Function).LISTBUILD7()
無效 lists
$LB(UndefinedVar) contains 1 elements
$LB(,) contains 2 elements
$LB() contains 1 elements
$LB(UndefinedVar) list value
 
在Cactch塊
System exception
Name: <NULL VALUE>
Location: zLISTBUILD7+12^PHA.TEST.Function.1
Code: 137
Data:
 

以下是有效的$LISTBUILD語句，該語句創建包含數據的列表元素，儘管此數據具有空字符串值：

/// d ##class(PHA.TEST.Function).LISTBUILD8()
ClassMethod LISTBUILD8()
{
    SET x=$LISTBUILD("")
    WRITE "list contains ",$LISTLENGTH(x)," elements",!
    WRITE "list value is ",$LISTTOSTRING(x,"^"),!
    SET y=$LISTBUILD($CHAR(0))
    WRITE "list contains ",$LISTLENGTH(y)," elements",!
    WRITE "list value is ",$LISTTOSTRING(y,"^")
}

DHC-APP>d ##class(PHA.TEST.Function).LISTBUILD8()
list contains 1 elements
list value is
list contains 1 elements
list value is

嵌套LIST

列表的元素本身可以是列表。例如，以下語句生成一個三元素列表，其第三個元素是兩元素列表“ Walnut，Pecan”：

/// d ##class(PHA.TEST.Function).LISTBUILD9()
ClassMethod LISTBUILD9()
{
    SET nlist=$LISTBUILD("Apple","Pear",$LISTBUILD("Walnut","Pecan"))
    WRITE "嵌套 list 長度 is ",$LISTLENGTH($LIST(nlist,3)),!
    WRITE "滿 list 長度 is ",$LISTLENGTH(nlist),!
    WRITE "List is ",$LISTTOSTRING(nlist,"^"),!
}

DHC-APP>d ##class(PHA.TEST.Function).LISTBUILD9()
嵌套 list 長度 is 2
滿 list 長度 is 3
List is Apple^PearWalnutPecan
 

串聯LIST

使用連接運算符（_）連接兩個列表的結果是一個將兩個列表組合在一起的列表。

在以下示例中，連接兩個列表將創建一個列表，該列表與使用LISTBUILD創建的具有相同元素的列表相同：

/// d ##class(PHA.TEST.Function).LISTBUILD10()
ClassMethod LISTBUILD10()
{
    SET list1=$LISTBUILD("A","B")
    SET list2=$LISTBUILD("C","D","E")
    SET clist=list1_list2
    SET list=$LISTBUILD("A","B","C","D","E")
    IF clist=list {
        WRITE "相同",!
    } ELSE {
        WRITE "不同",!
    }
    WRITE "串聯 ",$LISTTOSTRING(clist,"^"),!
    WRITE "相同LIST ",$LISTTOSTRING(list,"^")
}

DHC-APP>d ##class(PHA.TEST.Function).LISTBUILD10()
相同
串聯 A^B^C^D^E
相同LIST A^B^C^D^E

不能將字符串連接到列表。嘗試這樣做會在第一次嘗試訪問結果時生成錯誤：

/// d ##class(PHA.TEST.Function).LISTBUILD11()
ClassMethod LISTBUILD11()
{
    TRY {
        SET list=$LISTBUILD("A","B")_"C"
        WRITE "$LISTBUILD 完成沒有錯誤",!
        SET listlen=$LISTLENGTH(list)
        WRITE "$LISTLENGTH 完成沒有錯誤",!
        SET listval=$LISTTOSTRING(list,"^")
        WRITE "$LISTTOSTRING 完成沒有錯誤",!
    }
    CATCH exp { WRITE !!,"在Catch中",!
        IF 1=exp.%IsA("%Exception.SystemException") {
            WRITE "系統異常",!
            WRITE "Name: ",$ZCVT(exp.Name,"O","HTML"),!
            WRITE "Location: ",exp.Location,!
            WRITE "Code: "
        } ELSE { 
            WRITE "其他異常",! RETURN 
        }
        WRITE exp.Code,!
        WRITE "Data: ",exp.Data,! 
        RETURN
    }
}

DHC-APP>d ##class(PHA.TEST.Function).LISTBUILD11()
$LISTBUILD 完成沒有錯誤
 
 
在Catch中
系統異常
Name: <LIST>
Location: zLISTBUILD11+4^PHA.TEST.Function.1
Code: 81
Data: