Learning
Community
Open Exchange
Global Masters
InterSystems IRIS Data Platform 2019.4 / Application Development / ObjectScript Reference / ObjectScript Functions / $LISTBUILD
Previous section   Next section

$LISTBUILD

Builds a list of elements from the specified expressions.

Synopsis

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

SET $LISTBUILD(var1,var2,...)=list
SET $LB(var1,var2,...)=list

Parameters

element An expression that specifies a list element value. Can be a single expression or an expression in a comma-separated list of expressions. A placeholder comma can be specified for an omitted element.
var A variable, specified as a single variable or as a variable in a comma-separated list of variables. A placeholder comma can be specified for an omitted variable. A var may be a variable of any type: local, process-private, or global, unsubscripted or subscripted.
list An expression that evaluates to a valid list. Because lists contain encoding, list must be created using $LISTBUILD or $LISTFROMSTRING, or extracted from another list using $LIST.

Description

$LISTBUILD has two syntax forms: $LISTBUILD and SET $LISTBUILD:
  • $LISTBUILD(element1,element2,...) takes one or more expressions and returns an encoded list structure with one element for each expression. Elements are placed in the list in the order specified. Elements are counted from 1.
  • SET $LISTBUILD(var1,var2,...)=list extracts multiple elements from a list into variables. It is similar to SET $LISTGET(var1,var2,...)=list. They differ in how they handle variables that are not assigned an explicit value: SET $LISTGET defines these variables (thus avoiding an <UNDEFINED> error), and assigns them the empty string (null value, overwriting any prior value. SET $LISTBUILD does not define these variables; if the variable had no prior value it generates an <UNDEFINED> error, if the variable had a prior value, this value is preserved.

$LISTBUILD(element1,element2,...)

The following functions can be used to create a list:
  • $LISTBUILD, which creates a list from multiple data items (strings or numerics), one list element per data item. $LISTBUILD can also be used to create list elements containing no data.
  • $LISTFROMSTRING, which creates a list from a single string containing multiple delimited elements.
  • $LIST, which extracts a sublist from an existing list.
  • The null string ("") is also considered to be a valid list. The null string ("") is used to represent a null list, a list containing no elements. Because it contains no list elements, $LISTLENGTH("") returns an element count of 0.
  • Certain $CHAR non-printing character combinations, such as $CHAR(1), $CHAR(2,1), and $CHAR(3,1,asciicode) can also return an encoded empty or one-element list.
You can use the $LISTVALID function to determine if an expression is a valid list.
$LISTBUILD is used with the other $LIST functions: $LISTDATA, $LISTFIND, $LISTGET, $LISTNEXT, $LISTLENGTH, $LISTSAME, and $LISTTOSTRING.
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 the same way, regardless of the hardware platform. Wide characters are represented as byte strings.
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 when comparing encoded lists. 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”) and $LISTBUILD(1.0) is not equal to $LISTBUILD(1). However, list display functions, such as $LIST and $LISTTOSTRING return numeric list element values in canonical form. Therefore $LIST($LISTBUILD(1),1)=$LIST($LISTBUILD("1"),1).
For the same reason, an encoded list 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.

SET $LISTBUILD

When used on the left side of the equal sign in a SET command, the $LISTBUILD function extracts multiple elements from a list as a single operation. The syntax is as follows:
SET $LISTBUILD(var1,var2,...)=list
The var arguments of SET $LISTBUILD are a comma-separated list of variables, each of which is set to the value of the list element in the corresponding position. Thus, var1 is set to the value of the first list element, var2 is set to the value of the second list element, and so forth. The var arguments do not have to be existing variables; the variable is defined when SET $LISTBUILD assigns it a value.
  • The number of var arguments may be less than or greater than the number of list elements. Unspecified var values retain their prior value; if previously undefined they remain undefined. Compare this behavior with SET $LISTGET. Excess list elements are ignored.
  • The var arguments and/or the list elements may contain omitted values, represented by placeholder commas. An omitted var argument is undefined. An omitted list element causes the corresponding var value to retain its prior value; if previously undefined it remains undefined. Compare this behavior with SET $LISTGET.
SET $LISTBUILD is an atomic operation. The maximum number of var arguments is 1024. Attempting to exceed this number results in a <SYNTAX> error.
If a var argument is an object property (object.property) the property must be multidimensional. Any property may be referenced as an i%property instance variable within an object method.
In the following examples, $LISTBUILD (on the right side of the equal sign) creates a list with four elements.
In the following example, SET $LISTBUILD extracts the first two elements from a list into two variables:
   SET colorlist=$LISTBUILD("red","blue","green","white")
   SET $LISTBUILD(a,b)=colorlist
   WRITE "a=",a," b=",b   /* a="red" b="blue" */
In the following example, SET $LISTBUILD extracts elements from a list into five variables. Because the specified list does not have a 5th element, the corresponding var variable (e) contains its prior value:
   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 */
In the following example, SET $LISTBUILD extracts elements from a list into four variables. Because the specified list does not have a 3rd element, the corresponding var variable (c) contains its prior value:
   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" */
In the following example, SET $LISTBUILD extracts elements from a list into four variables. Because the 3rd list element value is a nested list, the corresponding var variable (c) contains a list value:
   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" */

Examples

Many of the examples shown here use the $LISTTOSTRING function to convert the $LISTBUILD return value for display; $LISTBUILD returns an encoded string that cannot be displayed directly.
The following example produces the three-element list "Red,Blue,Green":
   SET colorlist=$LISTBUILD("Red","Blue","Green")
   WRITE $LISTTOSTRING(colorlist,"^")
The following example creates a list of six numeric elements that display as "3^0^44^5.6^33^400". Note that $LISTBUILD encodes numeric element values based on an optimized binary representation, which may not be the same as canonical form. List display functions such as $LIST and $LISTTOSTRING return numeric element values in canonical form:
   SET numlist=$LISTBUILD(003,0.00,44.0000000,5.6,+33,4E2)
   WRITE $LISTTOSTRING(numlist,"^")

Omitting Elements

Omitting an element expression defines an encoded element, but the data value of that element is undefined.
In the following example, the $LISTBUILD statements both produce a valid three-element list whose second element has an undefined value. Omitting an element and specifying an undefined variable for an element produces exactly the same result. $LISTBUILD can take an undefined variable as a list element without generating an error and the resulting list passes the $LISTVALID test. However, referencing an undefined list element with a list function such as $LIST or $LISTTOSTRING generates a <NULL VALUE> error:
   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 "These are valid lists",! }
   IF list1=list2 {WRITE "and they're identical"}
   ELSE {WRITE "They're not identical"}
The following example shows that an undefined element can be specified at the end of a list, as well as within a list. A list with trailing undefined elements is a valid list. However, referencing this undefined element with any list function generates a <NULL VALUE> error:
   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 "These are valid lists",! }
   IF list3=list4 {WRITE "and they're identical"}
   ELSE {WRITE "They're not identical"}
However, the following example produces a three-element list whose second element has a data value: the empty string. No error condition occurs when referencing the second element:
   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),! }

Lists with No Data or Null String Data

Any list created using $LISTBUILD contains at least one encoded list element. That element may or may not contain data. Because $LISTLENGTH counts elements, not data, any list created using $LISTBUILD has a list length of at least 1.
Referencing a $LISTBUILD element whose data value is undefined generates a <NULL VALUE> error. The following are all valid $LISTBUILD statements that create “empty” lists. However, attempting to reference an element is such a list results in a <NULL VALUE> error:
   TRY {
     SET x=$LISTBUILD(UndefinedVar)
     SET y=$LISTBUILD(,)
     SET z=$LISTBUILD()
     IF $LISTVALID(x)=1,$LISTVALID(y)=1,$LISTVALID(z)=1 {
        WRITE "These are valid lists",! }
     WRITE "$LB(UndefinedVar) contains ",$LISTLENGTH(x)," elements",!
     WRITE "$LB(,) contains ",$LISTLENGTH(y)," elements",!
     WRITE "$LB() contains ",$LISTLENGTH(z)," elements",!
     /* Attempt to use null lists */
     WRITE "$LB(UndefinedVar) list value ",$LISTTOSTRING(x,"^"),!
     WRITE "$LB(,) list value ",$LISTTOSTRING(y,"^"),!
     WRITE "$LB() list value ",$LISTTOSTRING(z,"^"),!
   }
     CATCH exp { WRITE !!,"In the CATCH block",!
           IF 1=exp.%IsA("%Exception.SystemException") {
              WRITE "System exception",!
              WRITE "Name: ",$ZCVT(exp.Name,"O","HTML"),!
              WRITE "Location: ",exp.Location,!
              WRITE "Code: "
            }
            ELSE { WRITE "Some other type of exception",! RETURN }
              WRITE exp.Code,!
              WRITE "Data: ",exp.Data,! 
              RETURN
     }
The following are valid $LISTBUILD statements that create a list element that contains data, though this data has a null string value:
  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,"^")

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":
  SET nlist=$LISTBUILD("Apple","Pear",$LISTBUILD("Walnut","Pecan"))
    WRITE "Nested list length is ",$LISTLENGTH($LIST(nlist,3)),!
    WRITE "Full list length is ",$LISTLENGTH(nlist),!
    WRITE "List is ",$LISTTOSTRING(nlist,"^"),!

Concatenating Lists

The result of concatenating two lists with the Concatenate operator (_) is a list that combines the two lists.
In the following example, concatenating two lists creates a list that is identical to a list with the same elements created using LISTBUILD:
  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 "they're identical",!}
    ELSE {WRITE "they're not identical",!}
  WRITE "concatenated ",$LISTTOSTRING(clist,"^"),!
  WRITE "same list as ",$LISTTOSTRING(list,"^")
You cannot concatenate a string to a list. Attempting to do so generates a <LIST> error the first time you attempt to access the result:
   TRY {
   SET list=$LISTBUILD("A","B")_"C"
     WRITE "$LISTBUILD completed without error",!
   SET listlen=$LISTLENGTH(list)
     WRITE "$LISTLENGTH completed without error",!
   SET listval=$LISTTOSTRING(list,"^")
      WRITE "$LISTTOSTRING completed without error",!
   }
   CATCH exp { WRITE !!,"In the CATCH block",!
        IF 1=exp.%IsA("%Exception.SystemException") {
           WRITE "System exception",!
           WRITE "Name: ",$ZCVT(exp.Name,"O","HTML"),!
           WRITE "Location: ",exp.Location,!
           WRITE "Code: "
        }
        ELSE { WRITE "Some other type of exception",! RETURN }
        WRITE exp.Code,!
        WRITE "Data: ",exp.Data,! 
        RETURN
   }
For further details on concatenation, see Operators in Using ObjectScript.

See Also

Previous section   Next section