$LISTLENGTH (ObjectScript)

Synopsis

$LISTLENGTH(list)
$LL(list)

Description

$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.

Examples

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:

   WRITE $LISTLENGTH($LISTBUILD("Red",,"Green"))

The following examples all return 1. $LISTLENGTH makes no distinction between an empty list element and a list element containing data:

  WRITE $LISTLENGTH($LB()),!
  WRITE $LISTLENGTH($LB(UndefinedVar)),!
  WRITE $LISTLENGTH($LB("")),!
  WRITE $LISTLENGTH($LB($CHAR(0))),!
  WRITE $LISTLENGTH($LB("John Smith"))

The following example returns 0. $LISTVALID considers the null string a valid list, but it contains no list elements:

   WRITE $LISTLENGTH("")

The following example returns 3, because the two placeholder commas represent 3 empty list elements:

   WRITE $LISTLENGTH($LB(,,))

$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()))),!
   WRITE $LISTLENGTH($LB($LB($LB("Fred")))),!
   WRITE $LISTLENGTH($LB($LB("Barney"_$LB("Fred")))),!
   WRITE $LISTLENGTH($LB("Fred"_$LB("Barney"_$LB("Wilma"))))

See Also

• $LIST function

• $LISTBUILD function

• $LISTDATA function

• $LISTFIND function

• $LISTFROMSTRING function

• $LISTGET function

• $LISTNEXT

• $LISTSAME function

• $LISTTOSTRING function

• $LISTUPDATE function

• $LISTVALID function