文章目录

第二十七章 Caché 函数大全 $LISTBUILD 函数
大纲
- 参数
描述
- $LISTBUILD(element1,element2,...)
- SET $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创建的列表中的元素没有用字符定界符标记，因此可以包含任何字符。

扫描二维码关注公众号，回复： 11781684 查看本文章

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

示例

这里显示的许多示例都使用`` $L I S T T O S T R I N G ‘ 函数转换 ‘$ 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: &lt;NULL VALUE&gt;
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: &lt;LIST&gt;
Location: zLISTBUILD11+4^PHA.TEST.Function.1
Code: 81
Data: