第二十六章 Caché 函数大全 $LIST 函数

返回或替换列表中的元素。

大纲

$LIST(list,position,end) 
$LI(list,position,end)  

SET $LIST(list,position,end)=value 
SET $LI(list,position,end)=value

参数

• list 计算结果为有效列表的表达式。由于列表包含编码，因此必须使用$LISTBUILD或$LISTFROMSTRING创建列表，或者使用$LIST从另一个列表中提取列表。在SET $LIST语法中，list必须是变量或多维属性。
• position 可选—整数代码，用于指定列表中从中检索子列表的起始位置。允许的值为n（从列表开头的整数），*（列表中的最后一个元素）和* -n（从列表末尾开始的相对偏移量）。 SET $LIST语法还支持* + n（要追加到列表末尾的元素的相对偏移整数计数）。因此，列表中的第一个元素为1，第二个元素为2，列表中的最后一个元素为*，倒数第二个元素为* -1。如果省略position，则默认为1。-1可以在较旧的代码中使用，以指定列表中的最后一个元素。反对使用-1时，不应与*，*-n或* + n相对偏移语法结合使用。
• end 可选—一个整数代码，用于指定列表的子列表的结束位置。可以是一个正整数，它指定从列表开头算起的位置数，也可以是一个符号代码，从列表末算起。与位置一起使用，并使用与位置相同的代码值。如果省略，则仅返回由position指定的单个元素。

描述

$LIST可以通过两种方式使用：

• 从列表中返回一个或多个元素。这使用$LIST（list，position，end）语法。它通过从列表的开头或结尾开始的偏移量定位元素。它返回单个元素作为字符串。它返回一系列元素作为列表。
• 替换列表中的一个或多个元素。替换元素的长度可以与原始元素相同，更长或更短。这使用SET $LIST（list，position，end）= value语法。

返回列表元素

$LIST返回列表中的单个元素或元素范围。返回的元素取决于所使用的参数。

• $LIST（list）以字符串形式返回list中的第一个元素。
• $LIST（list，position）以字符串形式返回由position指定的list元素。指定的位置不能是列表末尾以外的正整数，也不能是列表开头前的负整数。
• $LIST（list，position，end）返回一个“子列表”（编码列表字符串），其中包含从列表中检索到的一系列元素。范围是从指定的开始位置到指定的结束位置（含）。如果position和end指定相同的元素，则$LIST将此元素作为编码列表返回。

指定的位置不能是列表末尾以外的正整数，也不能是列表开头前的负整数。指定的末尾可以是列表末尾以外的正整数，但仅返回现有的列表元素。不执行元素填充。

注意：不应在循环结构中使用$LIST返回多个连续的元素值。尽管这可以工作，但效率非常低，因为$LIST必须在每次迭代的开始就计算该列表。$LISTNEXT函数是返回多个连续元素值的更有效的方法。

参数

list

包含一个或多个元素的编码列表字符串。可以使用$LISTBUILD或$LISTFROMSTRING创建列表，也可以使用$LIST函数从另一个列表中提取列表。 （空字符串（“”）和某些$CHAR非打印字符组合，例如$CHAR（1），$CHAR（2,1）和$CHAR（3,1，asciicode）也可以返回已编码的空字符或单元素列表。）。

返回一个或多个元素时，列表可以是变量或对象属性。

当$LIST与等号左侧的SET一起使用以替换一个或多个元素时，list可以是变量或多维属性引用；它不能是非多维对象属性。

以下是有效的列表参数：

/// d ##class(PHA.TEST.Function).LIST()
ClassMethod LIST()
{
    SET myList = $LISTBUILD("Red","Blue","Green","Yellow")
    WRITE !,$LIST(myList,2)   ; prints Blue
    SET subList = $LIST(myList,2,4)
    WRITE !,$LIST(subList,2)  ; prints Green
}

DHC-APP>d ##class(PHA.TEST.Function).LIST()
 
Blue
Green

在下面的示例中，subList不是有效的列表参数，因为它是作为普通字符串而不是编码的列表字符串返回的单个元素：

/// d ##class(PHA.TEST.Function).LIST1()
ClassMethod LIST1()
{
    SET myList = $LISTBUILD("Red","Blue","Green","Yellow")
    SET subList = $LIST(myList,2)
    WRITE $LIST(subList,1)
}

DHC-APP>d ##class(PHA.TEST.Function).LIST1()
 
 WRITE $LIST(subList,1) }
 ^
<LIST>zLIST1+3^PHA.TEST.Function.1

在SET $LIST语法格式中，list不能是非多维对象属性。

position

要返回（或替换）的列表元素的位置（元素计数）。单个元素作为字符串返回。列表元素从1开始计数。如果省略position，则$LIST返回第一个元素。

• 如果position是一个正整数，则$LIST从列表的开头开始计数元素。如果position大于列表中的元素数，则Caché发出错误。
• 如果position为*（星号），则$LIST返回列表中的最后一个元素。
• 如果position为* -n（星号后跟负数），则$LIST通过从列表末尾向后偏移来计数元素。因此，*-0是列表中的最后一个元素，*-1是倒数第二个列表元素（从末尾偏移1）。如果位置相对偏移计数等于列表中的元素数（因此指定第0个元素），则Caché发出错误。如果位置相对偏移计数大于列表中的元素数，则Caché发出<RANGE>错误。
• 仅适用于SET $LIST语法—如果position为* + n（星号后跟一个正数），则SET $LIST会在列表末尾附加偏移量。因此，* + 1在列表末尾附加一个元素，* + 2在列表末尾两个位置附加一个元素，并以空字符串元素填充。
• 如果position为0或-0，则Caché发出<NULL VALUE>错误。

如果指定了end参数，则position指定元素范围中的第一个元素。一定范围的元素总是作为编码列表字符串返回。即使仅返回一个元素（当位置和结尾为相同数字时），该值也作为编码列表字符串返回。因此，$LIST（x，2）是与$LIST（x，2,2）相同的元素，但数据值不同。

end

最后一个元素在一系列元素中的位置，指定为整数。必须指定位置以指定结束。如果end是小数，则将其截断为整数部分。

指定end时，返回的值是编码列表字符串。由于这种编码，这样的字符串只能由其他$LIST函数处理。

• position < end: 如果end和position是正整数，而position < end $LIST返回一个编码的子列表，其中包含指定的元素列表，包括position和end元素。如果position为0或1，则子列表从列表中的第一个元素开始。如果end大于list中的元素数，则$LIST返回一个编码的子列表，该子列表包含从位置到列表末尾的所有元素。如果end是* -n，则position可以是正整数，也可以是大于或等于此结束位置的* -n值。因此，$LIST（fourlist，*-1，*），$LIST（fourlist，*-3，*-2），$LIST（fourlist，2，*-1）都是有效的子列表。
• position = end:如果end和position计算为同一元素，则$LIST返回包含该单个元素的编码子列表。例如，在具有四个元素的列表中，结尾和位置可以相同（$LIST（fourlist，2,2），$LIST（fourlist，*，*）或$LIST（fourlist，*-2，*-2 ）），也可以指定相同的元素（$LIST（fourlist，4，*），$LIST（fourlist，3，*-1））。
• position > end:如果position> end，则$LIST返回空字符串（“”）。例如，在具有四个元素的列表中，$LIST（fourlist，3,2），$LIST（fourlist，7，*）或$LIST（fourlist，*-1，*-2）都返回空字符串。
• position=0, 和 end: 如果指定了end，并且位置为零（0）或值为零的负偏移量，则位置0等于1。因此，如果end得出的元素位置大于零，则$LIST返回包含以下内容的编码子列表：从位置1到结束位置的元素。如果end也求值为零，则$LIST返回空字符串（“”），因为position> end。
• 仅适用于SET $LIST语法—如果end为* + n（星号后跟一个正数），则SET $LIST会在列表末尾附加偏移量的元素范围。如果position为* + n，则SET $LIST会附加一个值范围。如果position是一个正整数，或者* -n SET $LIST都替换并附加值。要替换最后一个元素并追加元素，请指定SET $LIST（mylist，* + 0，* + n）。如果指定范围的开始超出列表的末尾，则根据需要用空字符串元素填充列表。如果end大于提供的值范围，则不执行尾随填充。

不推荐使用–1

在较旧的代码中，位置或最终值为-1表示列表中的最后一个元素。值-1不能与*，* + n或* -n语法一起使用。

指定* -n和* + n参数值

使用变量指定* -n或* + n时，必须始终在参数本身中指定星号和符号字符。

以下是* -n的有效规格：

/// d ##class(PHA.TEST.Function).LIST2()
ClassMethod LIST2()
{
    SET count=2
    SET alph=$LISTBUILD("a","b","c","d")
    WRITE $LIST(alph,*-count)
}

DHC-APP>d ##class(PHA.TEST.Function).LIST2()
b

/// d ##class(PHA.TEST.Function).LIST3()
ClassMethod LIST3()
{
    SET count=-2
    SET alph=$LISTBUILD("a","b","c","d")
    WRITE $LIST(alph,*+count)
}

DHC-APP>d ##class(PHA.TEST.Function).LIST3()
b

以下是* + n的有效规范：

/// d ##class(PHA.TEST.Function).LIST4()
ClassMethod LIST4()
{
    SET count=2
    SET alph=$LISTBUILD("a","b","c","d")
    SET $LIST(alph,*+count)="F"
    WRITE $LISTTOSTRING(alph,"^",1)
}

DHC-APP>d ##class(PHA.TEST.Function).LIST4()
a^b^c^d^^F

这些参数值内允许使用空格。

$LIST错误

以下$LIST参数值会产生错误：

• 如果list参数的求值结果无效，则$LIST生成错误。可以使用$LISTVALID函数来确定列表是否有效。
• 如果list参数求值为包含空值的有效列表，或将列表和空值连接在一起，则$LIST（list）语法会生成错误，因为此语法试图将空值作为字符串返回。以下所有都是有效列表（根据$LISTVALID），其中$LIST会为其生成 <NULL VALUE>错误：

/// d ##class(PHA.TEST.Function).LIST5()
ClassMethod LIST5()
{
    // 以下均会发生错误
    WRITE $LIST(""),!
    WRITE $LIST($LB()),!
    WRITE $LIST($LB(UndefinedVar)),!
    WRITE $LIST($LB(,))
    WRITE $LIST($LB()_$LB("a","b","c"))
}

DHC-APP>d ##class(PHA.TEST.Function).LIST5()
 
 WRITE $LIST(""),!
 ^
<NULL VALUE>zLIST5+1^PHA.TEST.Function.1

如果$LIST（list，position）语法position参数指定一个null（不存在）元素，则$LIST会生成一个错误，因为此语法试图将null值作为字符串返回：

/// d ##class(PHA.TEST.Function).LIST6()
ClassMethod LIST6()
{
    SET mylist=$LISTBUILD("A",,"C")
    ZZDUMP $LIST(mylist,2)  ; generates a <NULL VALUE> error
}

DHC-APP>d ##class(PHA.TEST.Function).LIST6()
 
 ZZDUMP $LIST(mylist,2)  ; generates a <NULL VALUE> error
 ^
<NULL VALUE>zLIST6+2^PHA.TEST.Function.1

/// d ##class(PHA.TEST.Function).LIST7()
ClassMethod LIST7()
{
    SET mylist2=$LISTBUILD("A","B","C")
    WRITE $LIST(mylist2,4) ; generates a <NULL VALUE> error
}

DHC-APP 2d1>d ##class(PHA.TEST.Function).LIST7()
 
 WRITE $LIST(mylist2,4) ; generates a <NULL VALUE> error
 ^
<NULL VALUE>zLIST7+2^PHA.TEST.Function.1

• 如果$LIST（list，position）语法将位置参数指定为0，或者将负偏移量指定为第0个元素，则$LIST将生成错误。如果指定了end，则0为有效位置值，并解析为1。
• 如果position或end参数的*-n值指定的n值大于list中元素位置的数量，则$LIST生成错误。

/// d ##class(PHA.TEST.Function).LIST8()
ClassMethod LIST8()
{
    SET list2=$LISTBUILD("Brown","Black")
    WRITE $LIST(list2,*-2) ; generates a <NULL VALUE> error
    WRITE $LIST(list2,*-3) ; generates a <RANGE> error
}

DHC-APP>d ##class(PHA.TEST.Function).LIST8()
 
 WRITE $LIST(list2,*-2) ; generates a <NULL VALUE> error
 ^
<NULL VALUE>zLIST8+2^PHA.TEST.Function.1
DHC-APP 2d1>d ##class(PHA.TEST.Function).LIST8()
 
 WRITE $LIST(list2,*-3) ; generates a <RANGE> error
 ^
<RANGE>zLIST8+3^PHA.TEST.Function.1

因为$LISTLENGTH（“”）为0，所以* -1或更大的位置或结尾将导致错误：

DHC-APP>WRITE $LIST("",*-0)
 
WRITE $LIST("",*-0)
^
<NULL VALUE>
DHC-APP>WRITE $LIST("",*-1)
 
WRITE $LIST("",*-1)
^
<RANGE>
DHC-APP>WRITE $LIST("",0,*-1)
 

• 如果position参数或end参数的值小于-1，则$LIST生成错误。

使用SET $LIST替换元素

• 可以使用SET $LIST（list，position）删除元素，替换元素的值或将元素追加到列表中。在此两参数形式中，您将新元素值指定为字符串。
• 可以使用SET $LIST（list，position，end）删除一个或多个元素，替换一个或多个元素值，或将一个或多个元素附加到列表中。在此三参数形式中，必须指定新元素值作为编码列表。

当$LIST与等号左侧的SET一起使用时，list可以是有效的变量名。如果变量不存在，则SET $LIST对其进行定义。 list参数也可以是多维属性引用；它不能是非多维对象属性。尝试在非多维对象属性上使用SET $LIST会导致<OBJECT DISPATCH>错误。

如果函数使用相对偏移语法，则不能将SET（a，b，c，...）= value语法与等号左侧的$LIST（或$PIECE或$EXTRACT）一起使用：*表示结尾一个字符串，*-n或* + n代表距字符串末尾的相对偏移量。必须改为使用SET a = value，b = value，c = value，...语法。

还可以使用$LISTUPDATE替换列表中的一个或多个元素，或按元素位置将元素追加到列表中。 $LISTUPDATE替换列表元素，对每个元素替换执行布尔测试。与SET $LIST不同，$LISTUPDATE不会修改初始列表，而是返回带有指定元素替换的该列表的副本。

两参数运算

可以执行以下两个参数操作。注意，两参数运算将元素值指定为字符串。将元素值指定为列表会在列表中创建一个子列表。

• 用一个新值替换一个元素值：

/// w ##class(PHA.TEST.Function).listSpace(" a  b  c 姚 鑫 1  2    3  ")
ClassMethod listSpace(str)
{
    s newStr = $lts($lfs(str," "),"")
    q newStr
}

DHC-APP>w ##class(PHA.TEST.Function).listSpace(" a  b  c 姚 鑫 1  2    3  ")
abc姚鑫123

• 删除元素值（这会将值设置为null字符串；它不会删除元素位置）：

SET $LIST(fruit,2)=""

• 将元素追加到列表。可以使用* + n语法附加到列表的末尾，或附加到列表末尾的位置。 SET $LIST根据需要插入空值元素以填充到指定位置：

 SET $LIST(fruit,*+1)="plum"

• 用元素的子列表替换一个元素：

 SET $LIST(fruit,3)=$LISTBUILD("orange","banana")

三参数运算

可以执行以下三参数（范围）操作。请注意，即使指定单个元素值，范围操作也将元素值指定为列表。

• 用几个元素替换一个元素：

SET $LIST(fruit,3,3)=$LISTBUILD("orange","banana")

• 用相同数量的新值替换一系列元素值：

SET $LIST(fruit,2,3)=$LISTBUILD("orange","banana")

• 用更多或更少数量的新值替换一系列元素值：

SET $LIST(fruit,2,3)=$LISTBUILD("orange","banana","peach")

• 删除一系列元素值（这会将元素值设置为null字符串；它不会删除元素位置）：

SET $LIST(fruit,2,3)=$LISTBUILD("","")

• 删除一系列元素值及其位置：

SET $LIST(fruit,2,3)=""

• 将一系列元素添加到列表中。可以使用* + n语法附加到列表的末尾或列表末尾的位置。 SET $LIST根据需要插入空字符串值元素以填充到指定位置：

SET $LIST(fruit,*+1,*+2)=$LISTBUILD("plum","pear")

SET $LIST仅附加指定的元素值。如果结束位置大于指定的元素，则不会创建空的尾随元素位置。

示例

$LIST返回元素的示例

以下示例使用$LIST的2参数形式返回列表元素作为字符串：

以下两个$LIST语句返回“Red”，即列表中的第一个元素。默认情况下，第一个返回第一个元素，第二个返回第一个元素，因为position参数设置为1。该值以字符串形式返回：

/// d ##class(PHA.TEST.Function).LIST9()
ClassMethod LIST9()
{
    SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
    WRITE $LIST(colorlist),!
    WRITE $LIST(colorlist,1)
}

DHC-APP>d ##class(PHA.TEST.Function).LIST9()
Red
Red

以下两个$LIST语句返回“Orange”，即列表中的第二个元素。第一个从列表的开头算起，第二个从列表的末尾算起。该值以字符串形式返回：

/// d ##class(PHA.TEST.Function).LIST10()
ClassMethod LIST10()
{
    SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
    WRITE $LIST(colorlist,2),!
    WRITE $LIST(colorlist,*-4)
}

DHC-APP>d ##class(PHA.TEST.Function).LIST10()
Orange
Orange

以下示例使用$LIST的3参数形式返回一个或多个元素作为编码列表字符串。由于列表包含非打印编码字符，因此必须使用$LISTTOSTRING将子列表转换为可打印的字符串。

以下两个$LIST语句返回“Blue”，即列表中的第五个元素，作为编码后的列表字符串。第一个从列表的开头算起，第二个从列表的末尾算起。由于该元素被指定为范围，因此将其检索为包含一个元素的列表：

/// d ##class(PHA.TEST.Function).LIST11()
ClassMethod LIST11()
{
    SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
    WRITE $LISTTOSTRING($LIST(colorlist,5,5))
    WRITE $LISTTOSTRING($LIST(colorlist,*-1,*-1))
}

DHC-APP>d ##class(PHA.TEST.Function).LIST11()
BlueBlue

下面的示例返回“Red Orange Yellow”，这是一个三元素的列表字符串，从列表中的第一个元素开始，以第三个元素结束：

DHC-APP>SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
 
DHC-APP>WRITE $LISTTOSTRING($LIST(colorlist,1,3))
Red,Orange,Yellow

以下示例返回“ Green Blue Violet”，这是一个三元素的列表字符串，从列表中的第四个元素开始，到最后一个元素结束：

DHC-APP>SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
DHC-APP>WRITE $LISTTOSTRING($LIST(colorlist,4,*))
Green,Blue,Violet

以下示例从属性返回列表元素：

/// d ##class(PHA.TEST.Function).LIST12()
ClassMethod LIST12()
{
    SET cfg=##class(%iKnow.Configuration).%New("Trilingual",1,$LB("en","ch","es"))
    WRITE $LIST(cfg.Languages,2)
}

使用SET $LIST替换，删除或附加元素的示例

下面的示例显示SET $LIST替换第二个元素：

/// d ##class(PHA.TEST.Function).LIST13()
ClassMethod LIST13()
{
    SET fruit=$LISTBUILD("apple","onion","banana","pear")
    WRITE !,$LISTTOSTRING(fruit,"/")
    SET $LIST(fruit,2)="orange"
    WRITE !,$LISTTOSTRING(fruit,"/")
}

DHC-APP>d ##class(PHA.TEST.Function).LIST13()
 
apple/onion/banana/pear
apple/orange/banana/pear

下面的示例显示SET $LIST替换第二和第三个元素：

/// d ##class(PHA.TEST.Function).LIST14()
ClassMethod LIST14()
{
    SET fruit=$LISTBUILD("apple","potato","onion","pear")
    WRITE !,$LISTTOSTRING(fruit,"/")
    SET $LIST(fruit,2,3)=$LISTBUILD("orange","banana")
    WRITE !,$LISTTOSTRING(fruit,"/")
}

DHC-APP>d ##class(PHA.TEST.Function).LIST14()
 
apple/potato/onion/pear
apple/orange/banana/pear

下面的示例显示SET $LIST用四个元素替换第二个和第三个元素：

/// d ##class(PHA.TEST.Function).LIST15()
ClassMethod LIST15()
{
    SET fruit=$LISTBUILD("apple","potato","onion","pear")
    WRITE !,$LISTTOSTRING(fruit,"/")
    SET $LIST(fruit,2,3)=$LISTBUILD("orange","banana","peach","tangerine")
    WRITE !,$LISTTOSTRING(fruit,"/")
}

DHC-APP>d ##class(PHA.TEST.Function).LIST15()
 
apple/potato/onion/pear
apple/orange/banana/peach/tangerine/pear

以下示例显示SET $LIST将元素追加到列表的末尾：

/// d ##class(PHA.TEST.Function).LIST16()
ClassMethod LIST16()
{
    SET fruit=$LISTBUILD("apple","orange","banana","peach")
    WRITE $LL(fruit)," ",$LISTTOSTRING(fruit,"/",1),!
    SET $LIST(fruit,*+1)="pear"
    WRITE $LL(fruit)," ",$LISTTOSTRING(fruit,"/",1)
}

DHC-APP>d ##class(PHA.TEST.Function).LIST16()
4 apple/orange/banana/peach
5 apple/orange/banana/peach/pear

下面的示例显示SET $LIST在列表末尾的三个位置附加一个元素：

/// d ##class(PHA.TEST.Function).LIST17()
ClassMethod LIST17()
{
    SET fruit=$LISTBUILD("apple","orange","banana","peach")
    WRITE $LL(fruit)," ",$LISTTOSTRING(fruit,"/",1),!
    SET $LIST(fruit,*+3)="tangerine"
    WRITE $LL(fruit)," ",$LISTTOSTRING(fruit,"/",1)
}

DHC-APP>d ##class(PHA.TEST.Function).LIST17()
4 apple/orange/banana/peach
7 apple/orange/banana/peach///tangerine

以下四个示例显示了使用* -n语法的SET $LIST，以元素从列表末尾的偏移量替换元素。请注意，SET $LIST（x，*-n）和SET $LIST（x，n，*-n）执行不同的操作：SET $LIST（x，*-n）替换指定元素的值； SET $LIST（ x，n，*-n）删除指定范围的元素，然后追加指定列表。

要将倒数第二个元素替换为单个值，请使用SET $LIST（x，*-1）：

/// d ##class(PHA.TEST.Function).LIST18()
ClassMethod LIST18()
{
    SET fruit=$LISTBUILD("apple","banana","orange","potato","pear")
    WRITE !,"list length is ",$LISTLENGTH(fruit)," "
    WRITE $LISTTOSTRING(fruit,"/")
    SET $LIST(fruit,*-1)="peach"
    WRITE !,"list length is ",$LISTLENGTH(fruit)," "
    WRITE $LISTTOSTRING(fruit,"/")
}

DHC-APP>d ##class(PHA.TEST.Function).LIST18()
 
list length is 5 apple/banana/orange/potato/pear
list length is 5 apple/banana/orange/peach/pear

要从列表末尾按偏移量删除单个元素，请使用SET $LIST（x，*-n，*-n）=“”：

/// d ##class(PHA.TEST.Function).LIST19()
ClassMethod LIST19()
{
    SET fruit=$LISTBUILD("apple","banana","orange","potato","pear")
    WRITE !,"list length is ",$LISTLENGTH(fruit)," "
    WRITE $LISTTOSTRING(fruit,"/")
    SET $LIST(fruit,*-1,*-1)=""
    WRITE !,"list length is ",$LISTLENGTH(fruit)," "
    WRITE $LISTTOSTRING(fruit,"/")
}

DHC-APP>d ##class(PHA.TEST.Function).LIST19()
 
list length is 5 apple/banana/orange/potato/pear
list length is 4 apple/banana/orange/pear

要将单个元素从列表末尾的偏移量替换为元素列表，请使SET $LIST（x，*-n，*-n）= list：

/// d ##class(PHA.TEST.Function).LIST20()
ClassMethod LIST20()
{
    SET fruit=$LISTBUILD("apple","banana","potato","orange","pear")
    WRITE !,"list length is ",$LISTLENGTH(fruit)," "
    WRITE $LISTTOSTRING(fruit,"/")
    SET $LIST(fruit,*-2,*-2)=$LISTBUILD("peach","plum","quince")
    WRITE !,"list length is ",$LISTLENGTH(fruit)," "
    WRITE $LISTTOSTRING(fruit,"/")
}

DHC-APP>d ##class(PHA.TEST.Function).LIST20()
 
list length is 5 apple/banana/potato/orange/pear
list length is 7 apple/banana/peach/plum/quince/orange/pear

要将单个元素替换为列表末尾的子列表，请使用SET $LIST（x，*-n）= list：

/// d ##class(PHA.TEST.Function).LIST21()
ClassMethod LIST21()
{
    SET fruit=$LISTBUILD("apple","banana","potato","orange","pear")
    WRITE !,"list length is ",$LISTLENGTH(fruit)," "
    WRITE $LISTTOSTRING(fruit,"/")
    SET $LIST(fruit,*-2)=$LISTBUILD("peach","plum","quince")
    WRITE !,"list length is ",$LISTLENGTH(fruit)," "
    WRITE $LISTTOSTRING(fruit,"/")
}

DHC-APP> d ##class(PHA.TEST.Function).LIST21()
 
list length is 5 apple/banana/potato/orange/pear
list length is 5 apple/banana/peach�pluquince/orange/pear

下面的示例显示SET $LIST从列表中删除元素，从第三个元素到列表末尾：

/// d ##class(PHA.TEST.Function).LIST22()
ClassMethod LIST22()
{
    SET fruit=$LISTBUILD("apple","orange","onion","peanut","potato")
    WRITE !,"list length is ",$LISTLENGTH(fruit)," "
    WRITE $LISTTOSTRING(fruit,"/")
    SET $LIST(fruit,3,*)=""
    WRITE !,"list length is ",$LISTLENGTH(fruit)," "
    WRITE $LISTTOSTRING(fruit,"/")
}

DHC-APP>d ##class(PHA.TEST.Function).LIST22()
 
list length is 5 apple/orange/onion/peanut/potato
list length is 2 apple/orange

注意

Unicode

如果一个Unicode字符出现在列表元素中，则整个列表元素将表示为Unicode（宽）字符。列表中的其他元素不受影响。

以下示例显示了两个列表。 y列表由两个仅包含ASCII字符的元素组成。 z列表由两个元素组成：第一个元素包含Unicode字符（$CHAR（960）= pi符号）；第二个元素包含Unicode字符。第二个元素仅包含ASCII字符。

/// d ##class(PHA.TEST.Function).LIST23()
ClassMethod LIST23()
{
    IF $SYSTEM.Version.IsUnicode()  {
        SET y=$LISTBUILD("ABC"_$CHAR(68),"XYZ")
        SET z=$LISTBUILD("ABC"_$CHAR(960),"XYZ")
        WRITE !,"The ASCII list y elements: "
        ZZDUMP $LIST(y,1)
        ZZDUMP $LIST(y,2)
        WRITE !,"The Unicode list z elements: "
        ZZDUMP $LIST(z,1)
        ZZDUMP $LIST(z,2)
    }
    ELSE {WRITE "此示例需要Caché的Unicode安装"}
}

DHC-APP>d ##class(PHA.TEST.Function).LIST23()
 
The ASCII list y elements:
0000: 41 42 43 44                                             ABCD
0000: 58 59 5A                                                XYZ
The Unicode list z elements:
0000: 0041 0042 0043 03C0                                     ABCπ
0000: 58 59 5A                                                XYZ

请注意，Caché完全使用宽Unicode字符对z的第一个元素进行编码。 z的第二个元素不包含Unicode字符，因此Caché使用狭窄的ASCII字符对其进行编码。

$LIST与$EXTRACT和$PIECE相比

$LIST通过从列表的开头（或结尾）开始计数元素（而非字符）来确定编码列表中的元素。

$EXTRACT通过从字符串的开头（或结尾）开始计数字符来确定子字符串。 $EXTRACT将普通字符串作为输入。

$PIECE通过计算字符串中用户定义的定界符来确定子字符串。 $PIECE将包含要用作定界符的一个或多个字符实例的普通字符串作为输入。

$LIST不能用于普通字符串。 $PIECE和$EXTRACT不能用于编码列表。