Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?

$LISTLENGTH (ObjectScript)

Returns the number of elements in a specified list.




Argument Description
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