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

$LIST

Returns or replaces elements in a list.

Synopsis

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

$LIST(list,start1:end1,start2:end2...) 
$LI(list,position1:end1,position2:end2...) 

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

Parameters

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. In SET $LIST syntax, list must be a variable or a multi-dimensional property.
position
Optional $LIST(list,position,end) syntax — An integer code specifying the starting position in list from which to retrieve a sublist. Permitted values are n (integer count from beginning of list), * (last element in list), and *-n (relative offset count backwards from end of list). SET $LIST syntax also supports *+n (relative offset integer count of elements to append beyond the end of list). Thus, the first element in the list is 1, the second element is 2, the last element in the list is *, and the next-to-last element is *-1. If position is omitted, it defaults to 1.
-1 may be used in older code to specify the last element in the list. This deprecated use of -1 should not be combined with *, *-n, or *+n relative offset syntax.
end Optional $LIST(list,position,end) syntax — A code specifying the ending position of a sublist of list. Can be a positive integer specifying position count from the beginning of list or a symbolic code counting from the end of list. Used with position and uses the same code values as position. If omitted, only the single element specified by position is returned.
start1:end1
Optional $LIST(list,start1:end1,start2:end2) syntax — A pair of integers specifying the starting and ending position of a range to retrieve from list. start and end are connected by a colon. Only positive integers counts of elements from the beginning of list may be specified. A range pair may include integer counts beyond the end of list. start must be less than or equal to end.
You can specify any number of start:end range pairs as a comma-separated list. Range pairs may be specified in any order. Range pairs may overlap or may repeat list elements.

Description

$LIST can be used in three ways:
  • To retrieve a single range of elements) from list. This uses the $LIST(list,position,end) syntax. It locates elements by offset from either the beginning or the end of list. It returns a single element as a string. It return a range of elements as a list.
  • To retrieve multiple ranges of elements) from list. This uses the $LIST(list,position1:end1,position2:end2) syntax. It locates elements by offset from the beginning of list. It concatenates the ranges retrieved and returns the concatenated results as a list.
  • To replace an element (or elements) within list. The replacement element may be the same length, longer, or shorter than the original element. This uses the SET $LIST(list,position,end)=value syntax.

Returning a Single Sublist

$LIST(list,position,end) syntax:
$LIST returns a single sublist of elements. This sublist can contain one or more elements. The elements returned depend on the parameters used.
  • $LIST(list) returns the first element in list as a string.
  • $LIST(list,position) returns the element of list specified by position as a string. The specified position cannot be a positive integer count beyond the end of list or a negative integer count before the beginning of list.
  • $LIST(list,position,end) returns a “sublist” (an encoded list string) containing a range of elements retrieved from list. The range is from the specified start position through the specified end position (inclusive). If position and end specify the same element, $LIST returns this element as an encoded list.
    The specified position cannot be a positive integer count beyond the end of list or a negative integer count before the beginning of list. The specified end can be a positive integer count beyond the end of list but only the existing list elements are returned; no element padding is performed.
Note:
$LIST should not be used in a loop structure to return multiple successive element values. While this will work, it is highly inefficient, because $LIST must evaluate the list from the beginning with each iteration. The $LISTNEXT function is a far more efficient way to return multiple successive element values.

Returning Multiple Sublists

$LIST(list,start1:end1,start2:end2) syntax:
$LIST retrieves multiple range sublists of elements, then concatenates them into a single returned list. You can specify one or more start:end ranges; multiple ranges are separated by a comma. The retuned value is always a list structure, even if only one element is returned.
A range pair must consist of two positive integers, paired using a colon. This specifies a range of elements counting from the beginning of list; the start and end values are inclusive. The start value must be less than or equal to the end value. For example, 3:4 retrieves the third and fourth elements of list; 3:3 retrieves the third element of list; 4:3 is an invalid range and is skipped over without retrieving any elements. No values other than positive integers are permitted for start and end. Elements are counted from 1, zero should be avoided. If zero is specified it is converted to 1; therefore, 1:1, 0:1, 0:0, and 1:0 all retrieve the first element of list.
The specified start and/or end values can be a positive integer count beyond the end of list. A range sublist containing that range of elements is generated; if the range includes existing list elements they are included in the sublist, if the range includes elements beyond the end of list the sublist is padded with the appropriate number of null elements. Note that ZWRITE or $LISTTOSTRING(list,,1) must be used to display results that include null elements; WRITE does not display null elements, $LISTTOSTRING (by default) generates a <NULL VALUE> error.
The most efficient use of this syntax is to specify non-overlapping range pairs in ascending order: $LIST(mylist,2:2,4:7,10:20). However, comma-separated range pairs can be specified in any order. An element of list can be retrieved multiple times by different range pairs.
The following example retrieves four range pairs and concatenates them into a single list:
  SET mylist=$LISTBUILD("a","b","c","d","e","f","g")
  SET result=$LIST(mylist,2:2,1:4,7:9,1:2)
  ZWRITE result
returns: result=$lb("b","a","b","c","d","g",,,"a","b")

Parameters

list

An encoded list string containing one or more elements. Lists can be created using $LISTBUILD or $LISTFROMSTRING, or extracted from another list by using the $LIST function. (The empty string ("") and 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.)
When returning an element (or elements), list can be a variable or an object property.
When $LIST is used with SET on the left hand side of the equals sign to replace an element (or elements), list can be a variable or a multidimensional property reference; it cannot be a non-multidimensional object property.
The following are valid list arguments:
   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
In the following example, subList is not a valid list argument, because it is a single element returned as an ordinary string, not an encoded list string:
   SET myList = $LISTBUILD("Red","Blue","Green","Yellow")
   SET subList = $LIST(myList,2)
   WRITE $LIST(subList,1)
In SET $LIST syntax form, list cannot be a non-multidimensional object property.

position

The position (element count) of the list element to return (or replace). A single element is returned as a string. List elements are counted from 1. If position is omitted, $LIST returns the first element.
  • If position is a positive integer, $LIST counts elements from the beginning of list. If position is greater than the number of elements in list, InterSystems IRIS issues a <NULL VALUE> error.
  • If position is * (asterisk), $LIST returns the last element in list.
  • If position is *-n (an asterisk followed by a negative number), $LIST counts elements by offset backwards from the end of list. Thus, *-0 is the last element in the list, *-1 is the next-to-last list element (an offset of 1 from the end). If the position relative offset count is equal to the number of elements in list (and thus specifies the 0th element), InterSystems IRIS issues a <NULL VALUE> error. If the position relative offset count is greater than the number of elements in list, InterSystems IRIS issues a <RANGE> error.
  • For SET $LIST syntax only — If position is *+n (an asterisk followed by a positive number), SET $LIST appends elements by offset beyond the end of list. Thus, *+1 appends an element beyond the end of list, *+2 appends an element two positions beyond the end of list, padding with a null string element.
  • If position is 0 or -0, InterSystems IRIS issues a <NULL VALUE> error.
If the end parameter is specified, position specifies the first element in a range of elements. A range of elements is always returned as an encoded list string. Even when only one element is returned (when position and end are the same number) this value is returned as an encoded list string. Thus, $LIST(x,2) is the same element, but not the same data value as $LIST(x,2,2).

end

The position of the last element in a range of elements, specified as an integer. You must specify position to specify end. If end is a fractional number, it is truncated to its integer part.
When end is specified, the value returned is an encoded list string. Because of this encoding, such strings should only be processed by other $LIST functions.
  • position < end: If end and position are positive integers, and position < end, $LIST returns an encoded sublist containing the specified list of elements, inclusive of the position and end elements. If position is 0 or 1, the sublist begins with the first element in list. If end is greater than the number of elements in list, $LIST returns an encoded sublist containing all of the elements from position through the end of the list. If end is *-n, position can be a positive integer or a *-n value greater than or equal to this end position. Thus, $LIST(fourlist,*-1,*), $LIST(fourlist,*-3,*-2), $LIST(fourlist,2,*-1) are all valid sublists.
  • position = end: If end and position evaluate to the same element, $LIST returns an encoded sublist containing that single element. For example, in a list with four elements, end and position may be identical ($LIST(fourlist,2,2), $LIST(fourlist,*,*), or $LIST(fourlist,*-2,*-2)) or they may specify the same element ($LIST(fourlist,4,*), $LIST(fourlist,3,*-1)).
  • position > end: If position > end, $LIST returns the null string (""). For example, in a list with four elements, $LIST(fourlist,3,2), $LIST(fourlist,7,*), or $LIST(fourlist,*-1,*-2) all return the null string.
  • position=0, with end: If end is specified, and position is zero (0) or a negative offset that evaluates to position zero, position 0 is equivalent to 1. Therefore, if end evaluates to an element position greater than zero, $LIST returns an encoded sublist containing the elements from position 1 through the end position. If end also evaluates to element position zero, $LIST returns the null string (""), because position > end.
  • For SET $LIST syntax only — If end is *+n (an asterisk followed by a positive number), SET $LIST appends a range of elements by offset beyond the end of list. If position is *+n, SET $LIST appends a range of values. If position is a positive integer, or *-n SET $LIST both replaces and appends values. To replace the last element and append elements, specify SET $LIST(mylist,*+0,*+n). If the start of the specified range is beyond the end of list, the list is padded with a null string elements as needed. If end is larger than the supplied range of values, trailing padding is not performed.

Deprecated –1 Values

In older code, a position or end value of -1 represents the last element in the list. A value of -1 cannot be used with *, *+n, or *-n syntax.

Specifying *-n and *+n Parameter Values

When using a variable to specify *-n or *+n, you must always specify the asterisk and a sign character in the parameter itself.
The following are valid specifications of *-n:
  SET count=2
  SET alph=$LISTBUILD("a","b","c","d")
  WRITE $LIST(alph,*-count)
  SET count=-2
  SET alph=$LISTBUILD("a","b","c","d")
  WRITE $LIST(alph,*+count)
The following is a valid specification of *+n:
  SET count=2
  SET alph=$LISTBUILD("a","b","c","d")
  SET $LIST(alph,*+count)="F"
  WRITE $LISTTOSTRING(alph,"^",1)
Whitespace is permitted within these parameter values.

$LIST Errors

The following $LIST parameter values generate an error:
  • If the list parameter does not evaluate to a valid list, $LIST generates a <LIST> error. You can use the $LISTVALID function to determine if a list is valid.
  • If the list parameter evaluate to a valid list that contains a null value, or concatenates a list and a null value, $LIST(list) syntax generates a <NULL VALUE> error because this syntax is trying to return a null value as a string. All of the following are valid lists (according to $LISTVALID) for which $LIST generate a <NULL VALUE> error:
      WRITE $LIST(""),!
      WRITE $LIST($LB()),!
      WRITE $LIST($LB(UndefinedVar)),!
      WRITE $LIST($LB(,))
      WRITE $LIST($LB()_$LB("a","b","c"))
    
    If the $LIST(list,position) syntax position parameter specifies a null (non-existent) element, $LIST generates a <NULL VALUE> error because this syntax is trying to return a null value as a string:
       SET mylist=$LISTBUILD("A",,"C")
       ZZDUMP $LIST(mylist,2)  ; generates a <NULL VALUE> error
       SET mylist2=$LISTBUILD("A","B","C")
       WRITE $LIST(mylist2,4) ; generates a <NULL VALUE> error
  • If the $LIST(list,position) syntax specifies a position parameter of 0, or a negative relative offset that specifies the 0th element, $LIST generates a <NULL VALUE> error. If end is specified, 0 is a valid position value and is parsed as 1.
  • If the *-n value of the position or end parameter specifies an n value larger than the number of element positions in list, $LIST generates a <RANGE> error.
       SET list2=$LISTBUILD("Brown","Black")
       WRITE $LIST(list2,*-2) ; generates a <NULL VALUE> error
       WRITE $LIST(list2,*-3) ; generates a <RANGE> error
    Because $LISTLENGTH("") is 0, a position or end of *-1 or greater results in a <RANGE> error:
       WRITE $LIST("",*-0)   ; generates a <NULL VALUE> error
       WRITE $LIST("",*-1)   ; generates a <RANGE> error
       WRITE $LIST("",0,*-1) ; generates a <RANGE> error
  • If the value of the position parameter or the end parameter is less than -1, $LIST generates a <RANGE> error.

Replacing Elements Using SET $LIST

  • You can use SET $LIST(list,position) to remove an element, replace an element’s value, or append an element to the list. In this two-parameter form, you specify the new element value as a string.
  • You can use SET $LIST(list,position,end) to remove one or more elements, replace one or more element values, or append one or more elements to the list. In this three-parameter form, you must specify the new element value(s) as an encoded list.
(SET $LIST does not support $LIST(list,start1:end1,start2:end2) syntax.)
When $LIST is used with SET on the left hand side of the equals sign, list can be a valid variable name. If the variable does not exist, SET $LIST defines it. The list parameter can also be a multidimensional property reference; it cannot be a non-multidimensional object property. Attempting to use SET $LIST on a non-multidimensional object property results in an <OBJECT DISPATCH> error.
You cannot use SET (a,b,c,...)=value syntax with $LIST (or $PIECE or $EXTRACT) on the left of the equals sign, if the function uses relative offset syntax: * representing the end of a string and *-n or *+n representing relative offset from the end of the string. You must instead use SET a=value,b=value,c=value,... syntax.
You can also use $LISTUPDATE to replace one or more elements in a list or append element to a list by element position. $LISTUPDATE replaces list elements, performing a boolean test for each element replacement. Unlike SET $LIST, $LISTUPDATE does not modify the initial list, but returns a copy of that list with the specified element replacements.

Two Parameter Operations

You can perform the following two-parameter operations. Note that two-parameter operations specify an element value as a string. Specifying an element value as a list creates a sublist within the list.
  • Replace one element value with a new value:
      SET $LIST(fruit,2)="orange"   ; count from beginning of list
      SET $LIST(fruit,*)="pear"     ; element at end of list
      SET $LIST(fruit,*-2)="peach"  ; offset from end of list
    
  • Remove an element value (this sets the value to the null string; it does not remove the element position):
      SET $LIST(fruit,2)=""
  • Append an element to a list. You can append to the end of the list, or to a location past the end of the list, by using *+n syntax. SET $LIST inserts null value elements as needed to pad to the specified position:
      SET $LIST(fruit,*+1)="plum"
  • Replace one element with a sublist of elements:
      SET $LIST(fruit,3)=$LISTBUILD("orange","banana")

Three Parameter Operations

You can perform the following three-parameter (range) operations. Note that range operations specify an element values as a list, even when specifying a single element value.
  • Replace one element with several elements:
      SET $LIST(fruit,3,3)=$LISTBUILD("orange","banana")
  • Replace a range of element values with the same number of new values:
      SET $LIST(fruit,2,3)=$LISTBUILD("orange","banana")
  • Replace a range of element values with a larger or smaller number of new values:
      SET $LIST(fruit,2,3)=$LISTBUILD("orange","banana","peach")
  • Remove a range of element values (this sets the element values to the null string; it does not remove the element positions):
      SET $LIST(fruit,2,3)=$LISTBUILD("","")
  • Remove a range of element values and their positions:
      SET $LIST(fruit,2,3)=""
  • Append a range of element to a list. You can append to the end of the list, or to a location past the end of the list, by using *+n syntax. SET $LIST inserts null value elements as needed to pad to the specified position:
      SET $LIST(fruit,*+1,*+2)=$LISTBUILD("plum","pear")
    SET $LIST only appends the specified element values. If the end position is larger than the specified elements, empty trailing element positions are not created.

Examples

Examples of Returning Elements with $LIST

The following examples use the 2-parameter form of $LIST to return a list element as a string:
The following two $LIST statements return “Red”, the first element in the list. The first returns the first element by default, the second returns the first element because the position parameter is set to 1. The value is returned as a string:
   SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
   WRITE $LIST(colorlist),!
   WRITE $LIST(colorlist,1)
The following two $LIST statements return “Orange”, the second element in the list. The first counts from the beginning of the list, the second counts backwards from the end of the list. The value is returned as a string:
   SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
   WRITE $LIST(colorlist,2),!
   WRITE $LIST(colorlist,*-4)

The following examples use the 3-parameter form of $LIST to return one or more elements as an encoded list string. Because a list contains non-printing encoding character, you must use $LISTTOSTRING to convert the sublist to a printable string.
The following two $LIST statements return “Blue”, the fifth element in the list as an encoded list string. The first counts from the beginning of the list, the second counts backwards from the end of the list. Because the element is specified as a range, it is retrieved as a list consisting of one element:
   SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
   WRITE $LISTTOSTRING($LIST(colorlist,5,5))
   WRITE $LISTTOSTRING($LIST(colorlist,*-1,*-1))

The following example returns “Red Orange Yellow”, a three-element list string beginning with the first element and ending with the third element in the list:
   SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
   WRITE $LISTTOSTRING($LIST(colorlist,1,3))

The following example returns “Green Blue Violet”, a three-element list string beginning with the fourth element and ending with the last element in the list:
   SET colorlist=$LISTBUILD("Red","Orange","Yellow","Green","Blue","Violet")
   WRITE $LISTTOSTRING($LIST(colorlist,4,*))

The following example returns a list element from a property:
  SET cfg=##class(%iKnow.Configuration).%New("Trilingual",1,$LB("en","fr","es"))
  WRITE $LIST(cfg.Languages,2)

Examples of Replacing, Removing, or Appending Elements with SET $LIST

The following example shows SET $LIST replacing the second element:
   SET fruit=$LISTBUILD("apple","onion","banana","pear")
   WRITE !,$LISTTOSTRING(fruit,"/")
   SET $LIST(fruit,2)="orange"
   WRITE !,$LISTTOSTRING(fruit,"/")
The following example shows SET $LIST replacing the second and third elements:
   SET fruit=$LISTBUILD("apple","potato","onion","pear")
   WRITE !,$LISTTOSTRING(fruit,"/")
   SET $LIST(fruit,2,3)=$LISTBUILD("orange","banana")
   WRITE !,$LISTTOSTRING(fruit,"/")
The following example shows SET $LIST replacing the second and third elements with four elements:
   SET fruit=$LISTBUILD("apple","potato","onion","pear")
   WRITE !,$LISTTOSTRING(fruit,"/")
   SET $LIST(fruit,2,3)=$LISTBUILD("orange","banana","peach","tangerine")
   WRITE !,$LISTTOSTRING(fruit,"/")
The following example shows SET $LIST appending an element to the end of the list:
   SET fruit=$LISTBUILD("apple","orange","banana","peach")
   WRITE $LL(fruit)," ",$LISTTOSTRING(fruit,"/",1),!
   SET $LIST(fruit,*+1)="pear"
   WRITE $LL(fruit)," ",$LISTTOSTRING(fruit,"/",1)
The following example shows SET $LIST appending an element three positions past the end of the list:
   SET fruit=$LISTBUILD("apple","orange","banana","peach")
   WRITE $LL(fruit)," ",$LISTTOSTRING(fruit,"/",1),!
   SET $LIST(fruit,*+3)="tangerine"
   WRITE $LL(fruit)," ",$LISTTOSTRING(fruit,"/",1)
The following four examples show SET $LIST using *-n syntax to replace elements by offset from the end of the list. Note that SET $LIST(x,*-n) and SET $LIST(x,n,*-n perform different operations: SET $LIST(x,*-n) replaces the value of the specified element; SET $LIST(x,n,*-n) deletes the specified range of elements, then appends the specified list.
To replace the next-to-last element with a single value, use SET $LIST(x,*-1):
   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,"/")
To remove a single element by offset from the end of the list, use SET $LIST(x,*-n,*-n)="":
   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,"/")
To replace a single element by offset from the end of the list with a list of elements, use SET $LIST(x,*-n,*-n)=list:
   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,"/")
To replace a single element by offset from the end of the list with a sublist, use SET $LIST(x,*-n)=list:
   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,"/")
The following example shows SET $LIST removing elements from the list, beginning with the third element through the end of the list:
   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,"/")

Notes

Unicode

If one Unicode character appears in a list element, that entire list element is represented as Unicode (wide) characters. Other elements in the list are not affected.
The following example shows two lists. The y list consists of two elements which contain only ASCII characters. The z list consists of two elements: the first element contains a Unicode character ($CHAR(960) = the pi symbol); the second element contains only ASCII characters.
   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)
Note that InterSystems IRIS encodes the first element of z entirely in wide Unicode characters. The second element of z contains no Unicode characters, and thus InterSystems IRIS encodes it using narrow ASCII characters.

$LIST Compared with $EXTRACT and $PIECE

$LIST determines an element from an encoded list by counting elements (not characters) from the beginning (or end) of the list.
$EXTRACT determines a substring by counting characters from the beginning (or end) of a string. $EXTRACT takes as input an ordinary character string.
$PIECE determines a substring by counting user-defined delimiter characters within the string. $PIECE takes as input an ordinary character string containing multiple instances of a character (or string) intended for use as a delimiter.
$LIST cannot be used on ordinary strings. $PIECE and $EXTRACT cannot be used on encoded lists.

See Also

Previous section   Next section