第二十七章 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: