第八十一章 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 总是以相同的顺序存储这些字节，而不管硬件平台如何。宽字符表示为字节字符串。