$LISTBUILD ($LB)

Builds a list of elements from the specified expressions.

Synopsis

$LISTBUILD(element,...) $LB(element,...)

Parameter

element

Element values to include in a Caché list. An expression that resolves to a number or string. Commonly, multiple element values are specified, separated by commas. To include a comma within an element, make the element a quoted string.

Description

$LISTBUILD takes one or more element values and returns a Caché list structure containing a corresponding list of elements.

The following functions can be used to create a list:

$LISTBUILD, which creates a list from multiple strings, one string per element.
$LISTFROMSTRING, which creates a list from a single string containing multiple delimited elements.
$LIST, which extracts a sublist from an existing list.

$LISTBUILD is used with the other $LIST functions: $LISTDATA, $LISTFIND, $LISTGET, $LISTLENGTH, $LISTSAME, and $LISTTOSTRING.

Note:

$LISTBUILD and the other $LIST functions use an optimized binary representation to store data elements. For this reason, equivalency tests may not work as expected with some $LIST data. Data that might, in other contexts, be considered equivalent, may have a different internal representation. For example, $LISTBUILD(1) is not equal to $LISTBUILD(“1”).

For the same reason, a list string value returned by $LISTBUILD should not be used in character search and parse functions that use a delimiter character, such as $PIECE and the two-argument form of $LENGTH. Elements in a list created by $LISTBUILD are not marked by a character delimiter, and thus can contain any character.

Examples

The following example produces the three-element list "Red,Blue,Green":

x=$LISTBUILD("Red","Blue","Green")
PRINT $LIST(x,1,3)

Notes

Omitting Parameters

Omitting an element expression yields an element whose value is undefined. For example, the following $LISTBUILD statement produces a three-element list whose second element has an undefined value; referencing the second element with the $LIST function will produce a <NULL VALUE> error.

PRINT $LIST($LISTBUILD("Red",,"Green"),2)

However, the following produces a three-element list whose second element is a null string. No error condition exists.

PRINT $LIST($LISTBUILD("Red","","Green"),2)

Additionally, if a $LISTBUILD expression is undefined, the corresponding list element has an undefined value. The following two expressions both produce the same two-element list whose first element is "Red" and whose second element has an undefined value:

PRINT $LISTBUILD("Red",)
PRINT $LISTBUILD("Red",Z)

Providing No Parameters

Invoking the $LISTBUILD function with no parameters returns a list with one element whose data value is undefined. This is not the same as a null string:

x=$LISTBUILD()
y=$LISTBUILD("")
PRINT x
PRINT y

Nesting Lists

An element of a list may itself be a list. For example, the following statement produces a three-element list whose third element is the two-element list, "Walnut,Pecan":

x=$LISTBUILD("Apple","Pear",$LISTBUILD("Walnut","Pecan"))
PRINT $LIST(x,3)

Concatenating Lists

The result of concatenating two lists with the Concatenation Operator (:) is another list. For example, the following two WRITE statements produce the same list, "A,B,C":

PRINT $LIST($LISTBUILD("A","B"):$LISTBUILD("C"),0,-1)
PRINT $LIST($LISTBUILD("A","B","C"),0,-1)

A null string ("") is an empty list. For example, the following two expressions each produce the same two-element list:

PRINT $LISTBUILD("A","B"):""
PRINT $LISTBUILD("A","B")

However, the following two expressions each produce a three-element list:

PRINT $LISTBUILD("A","B"):$LISTBUILD("")
PRINT $LISTBUILD("A","B"):$LISTBUILD()

Unicode

If one or more characters in a list element is a wide (Unicode) character, all characters in that element are represented as wide characters. To ensure compatibility across systems, $LISTBUILD always stores these bytes in the same order, regardless of the hardware platform. Wide characters are represented as byte strings. Therefore, the length reflects the number of bytes, not the number of Unicode characters.

In the following example, the first element has a length of ten: four characters, each two bytes long, plus the length and data type bytes. The data type byte is 02 (Unicode string). Each character is represented by two bytes in little-endian order. The second element has a length of five: three characters, plus the length and data type bytes. The data type byte is 01 (Binary string).

z=$LISTBUILD(CHAR(987):"ABC","ABC")
PRINT LEN(z)