第八十一章 SQL函数 $LISTBUILD

从字符串构建列表的列表函数。

大纲

$LISTBUILD(element [,...])

参数

• element - 任何表达式，或逗号分隔的表达式列表

描述

$LISTBUILD 接受一个或多个表达式，并为每个表达式返回一个包含一个元素的列表。

以下函数可用于创建列表：

• $LISTBUILD，它从多个字符串创建一个列表，每个元素一个字符串。
• $LISTFROMSTRING，它从包含多个分隔元素的单个字符串创建一个列表。
• $LIST，从现有列表中提取子列表。

$LISTBUILD 与其他 SQL 列表函数一起使用：$LIST、$LISTDATA、$LISTFIND、$LISTFROMSTRING、$LISTGET、$LISTLENGTH 和 $LISTTOSTRING。

注意：$LISTBUILD 和其他 $LIST 函数使用优化的二进制表示来存储数据元素。出于这个原因，等效性测试可能无法对某些 $LIST 数据按预期工作。在其他情况下可能被视为等效的数据可能具有不同的内部表示。例如，$LISTBUILD(1) 不等于 $LISTBUILD('1')。

出于同样的原因，$LISTBUILD 返回的列表字符串值不应用于使用分隔符的字符搜索和解析函数，例如 $PIECE 和 $LENGTH 的两个参数形式。由 $LISTBUILD 创建的列表中的元素不使用字符分隔符进行标记，因此可以包含任何字符。

示例

以下嵌入式 SQL 示例采用三个字符串并生成一个三元素列表：

/// d ##class(PHA.TEST.SQLFunction).Lb()
ClassMethod Lb()
{
	s x = "Red"
	s y = "White"
	s z = "Blue"
	&sql(
		SELECT $LISTBUILD(:x, :y, :z)
		INTO :listout
	)
	if SQLCODE = 0 {
		w listout," length ",$LISTLENGTH(listout)
	} else {
		w "Error code:",SQLCODE
	}
}

DHC-APP>d ##class(PHA.TEST.SQLFunction).Lb()
RedWhiteBlue length 3

注意

省略参数

省略元素表达式会产生一个值为 NULL 的元素。例如，以下嵌入式 SQL 包含两个 $LISTBUILD 语句，它们都生成一个三元素列表，其第二个元素具有未定义 (NULL) 值：

/// d ##class(PHA.TEST.SQLFunction).Lb1()
ClassMethod Lb1()
{
	s x = "Red"
	s y = "White"
	s z = "Blue"
	&sql(
		SELECT $LISTBUILD(:x, ,:z),
			$LISTBUILD(:x, '', :z)
		INTO :list1, :list2)
	if SQLCODE = 0 {
		w list1," length ",$LISTLENGTH(list1),!
		w list2," length ",$LISTLENGTH(list2)
	} else {
		w "Error code:",SQLCODE
	}
}

DHC-APP>d ##class(PHA.TEST.SQLFunction).Lb1()
RedBlue length 3
RedBlue length 3

此外，如果 $LISTBUILD 表达式未定义，则相应的列表元素具有未定义的值。以下嵌入式 SQL 示例生成一个双元素列表，其第一个元素为“Red”，第二个元素具有未定义的值：

/// d ##class(PHA.TEST.SQLFunction).Lb2()
ClassMethod Lb2()
{
	&sql(
		SELECT $LISTBUILD('Red',:z)
		INTO :list1
	)
	if SQLCODE = 0 {
		w list1," length ",$LISTLENGTH(list1)
	} else {
		w "Error code:",SQLCODE
	}
}

DHC-APP>d ##class(PHA.TEST.SQLFunction).Lb2()
Red length 2

以下嵌入式 SQL 示例生成一个包含两个元素的列表。尾随逗号表示第二个元素具有未定义的值：

/// d ##class(PHA.TEST.SQLFunction).Lb3()
ClassMethod Lb3()
{
	&sql(
		SELECT $LISTBUILD('Red',)
		INTO :list1
	)
	if SQLCODE = 0 {
		w list1," length ",$LISTLENGTH(list1)
	} else {
		w "Error code:",SQLCODE
	}
}

DHC-APP>d ##class(PHA.TEST.SQLFunction).Lb3()
Red length 2

不提供任何参数

调用不带参数的 $LISTBUILD 函数会返回一个列表，其中包含一个数据值未定义的元素。这与 NULL 不同。以下是创建“空”列表的有效 $LISTBUILD 语句：

/// d ##class(PHA.TEST.SQLFunction).Lb4()
ClassMethod Lb4()
{
	&sql(
		SELECT $LISTBUILD(),
			$LISTBUILD(NULL)
		INTO :list1, :list2
	)
	if SQLCODE = 0 {
		ZZDUMP list1
		w !,"length ",$LISTLENGTH(list1),!
		ZZDUMP list2
		w !,"length ",$LISTLENGTH(list2),!
	} else {
		w "Error code:",SQLCODE
	}
}

DHC-APP>d ##class(PHA.TEST.SQLFunction).Lb4()
 
0000: 01                                                      .
length 1
 
0000: 02 01                                                   ..
length 1

以下是创建包含空字符串的列表元素的有效 $LISTBUILD 语句：

/// d ##class(PHA.TEST.SQLFunction).Lb5()
ClassMethod Lb5()
{
	&sql(
		SELECT $LISTBUILD(''),
	          $LISTBUILD(CHAR(0))
		INTO :list1, :list2
	)
	if SQLCODE = 0 {
		ZZDUMP list1
		w !,"length ",$LISTLENGTH(list1),!
		ZZDUMP list2
		w !,"length ",$LISTLENGTH(list2),!
	} else {
		w "Error code:",SQLCODE
	}
}

DHC-APP> d ##class(PHA.TEST.SQLFunction).Lb5()
 
0000: 03 01 00                                                ...
length 1
 
0000: 03 01 00                                                ...
length 1

嵌套List

列表的元素本身可能是一个列表。例如，以下语句生成一个三元素列表，其第三个元素是二元素列表“Walnut,Pecan”：

SELECT $LISTBUILD('Apple','Pear',$LISTBUILD('Walnut','Pecan'))

0x07014170706C650601506561721101080157616C6E75740701506563616E

连接List

使用 SQL 连接运算符 (||) 连接两个列表的结果是另一个列表。例如，以下 SELECT 项生成相同的列表“A,B,C”：

SELECT $LISTBUILD('A','B','C') AS List,
  $LISTBUILD('A','B')||$LISTBUILD('C') AS CatList

0x030141030142030143	ABC

在以下示例中，前两个选择项生成相同的二元素列表；第三个选择项导致 NULL（因为将 NULL 连接到任何内容都会导致 NULL）；第四个和第五个选择项产生相同的三元素列表：

SELECT
  $LISTBUILD('A','B') AS List,
  $LISTBUILD('A','B')||'' AS CatEStr,
  $LISTBUILD('A','B')||NULL AS CatNull,
  $LISTBUILD('A','B')||$LISTBUILD('') AS CatEList,
  $LISTBUILD('A','B')||$LISTBUILD(NULL) AS CatNList

Unicode

如果列表元素中的一个或多个字符是宽 (Unicode) 字符，则该元素中的所有字符都表示为宽字符。为了确保跨系统的兼容性，$LISTBUILD 总是以相同的顺序存储这些字节，而不管硬件平台如何。宽字符表示为字节字符串。