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


Returns the number of elements in a specified list.




list Any expression that evaluates to a list. A list can be created using $LISTBUILD or $LISTFROMSTRING, or extracted from another list using $LIST.


$LISTLENGTH returns the number of elements in list. $LISTLENGTH counts as a list element every designated list position, whether or not that position contains data.
You can use the $LISTVALID function to determine if list is a valid list. If list is not a valid list, the system generates a <LIST> error.
An “empty” list created by $LISTBUILD defines an encoded list element, although that list element contains no data. Because $LISTLENGTH counts list elements (not elements containing data), an “empty” list has a $LISTLENGTH count of 1.
The null string ("") is used to represent a null list, a list containing no elements. Because it contains no list elements, it has a $LISTLENGTH count of 0.


The following example returns 3, because there are 3 elements in the list:
   WRITE $LISTLENGTH($LISTBUILD("Red","Blue","Green"))
The following example also returns 3, even though the second element in the list contains no data:
The following examples all return 1. $LISTLENGTH makes no distinction between an empty list element and a list element containing data:
  WRITE $LISTLENGTH($LB(UndefinedVar)),!
  WRITE $LISTLENGTH($LB("John Smith"))
The following example returns 0. $LISTVALID considers the null string a valid list, but it contains no list elements:
The following example returns 3, because the two placeholder commas represent 3 empty list elements:

$LISTLENGTH and Concatenation

Concatenating two lists always results in a $LISTLENGTH equal to the sum of the lengths of the lists. This is true even when concatenating empty lists, or concatenating a null string to a list.
The following example all return a list length of 3:
  WRITE $LISTLENGTH($LB()_$LB("a","b")),!
  WRITE $LISTLENGTH($LB("a")_$LB(UndefinedVar)_$LB("c")),!
  WRITE $LISTLENGTH($LB("")_$LB()_$LB(UndefinedVar)),!
  WRITE $LISTLENGTH(""_$LB("a","b","c")),!
  WRITE $LISTLENGTH($LB("a","b")_""_$LB("c"))

$LISTLENGTH and Nested Lists

The following example returns 3, because $LISTLENGTH does not recognize the individual elements in a nested list, and treats it as a single list element:
   WRITE $LISTLENGTH($LB("Apple","Pear",$LB("Walnut","Pecan")))
The following examples all return 1, because $LISTLENGTH counts only the outermost nested list:
   WRITE $LISTLENGTH($LB($LB($LB("Fred")))),!
   WRITE $LISTLENGTH($LB($LB("Barney"_$LB("Fred")))),!
   WRITE $LISTLENGTH($LB("Fred"_$LB("Barney"_$LB("Wilma"))))

See Also

Previous section   Next section