$LISTSAME ($LS)

Compares two lists and returns a boolean value.

Synopsis

$LISTSAME(list1,list2)
$LS(list1,list2)

Parameters

list	An expression that resolves to a Caché list. A Caché list is created using $LISTBUILD or $LISTFROMSTRING, or extracted from another list using $LIST.

Description

$LISTSAME compares the contents of two lists and returns 1 if the lists are identical. If the lists are not identical, $LISTSAME returns 0.

A Caché list can either be a list created using $LISTBUILD, or a null string (""). If list is not a valid list, you receive a <LIST> error.

Examples

The following example returns 1, because the two lists are identical:

x = $LISTBUILD("Red","Blue","Green")
y = $LISTBUILD("Red","Blue","Green")
PRINT $LISTSAME(x,y)

The following example returns 0, because the two lists are not identical:

x = $LISTBUILD("Red","Blue","Yellow")
y = $LISTBUILD("Red","Blue","Green")
PRINT $LISTSAME(x,y)

Notes

Identical Lists

$LISTSAME considers two lists to be identical if the string representations of the two lists are identical. This is not the same equivalence test as the one used by other list operations, which test using the internal representation of a list. This distinction is easily seen when comparing a number and a numeric string, as in the following example:

x = $LISTBUILD("365")
y = $LISTBUILD(365)
   IF x'=y { PRINT "number and numeric string lists differ" }
PRINT $LISTSAME(x,y)," number and numeric string lists identical"

The IF comparison tests the internal representations of these lists (which are not identical). $LISTSAME performs a string conversion on both lists, compares them, and finds them identical.

The following example shows two lists with various representations of numeric elements. $LISTSAME considers these two lists to be identical:

x = $LISTBUILD("360","361","362","363","364","365","366")
y = $LISTBUILD(00360.000,(19*19),+"362",363,364.0,+365,"3"_"66")
PRINT $LISTSAME(x,y)," lists are identical"

In the following example, both $LISTSAME comparisons returns 0, because these lists are not considered identical:

x=$LISTBUILD("Apple","Pear","Walnut","Pecan")
y=$LISTBUILD("Apple","Pear",$LISTBUILD("Walnut","Pecan"))
z=$LISTBUILD("Apple","Pear","Walnut","Pecan","")
PRINT $LISTSAME(x,y)," nested list"
PRINT $LISTSAME(x,z)," null string is list item"

The following example returns 1, because the lists are considered identical:

x=$LISTBUILD("Apple","Pear","Walnut","Pecan")
y=$LISTBUILD("Apple","Pear")_$LISTBUILD("Walnut","Pecan")
PRINT $LISTSAME(x,y)," concatenate lists"

Null String and Null List

A list containing the null string (an empty string) as its sole element is a valid list. The null string by itself is also considered a valid list. However these two (a null string and a null list) are not considered identical, as shown in the following example:

PRINT $LISTSAME($LISTBUILD(""),$LISTBUILD(""))," null lists"
PRINT $LISTSAME("","")," null strings"
PRINT $LISTSAME($LISTBUILD(""),"")," null list and null string"

Normally, a string is not a valid $LISTSAME argument, and $LISTSAME issues a <LIST> error. However, the following $LISTSAME comparisons complete successfully and return 0. The null string and the string “abc” are compared and found not to be identical. These null string comparisons do not issue a <LIST> error:

PRINT $LISTSAME("","abc")
PRINT $LISTSAME("abc","")

The following $LISTSAME comparisons do issue a <LIST> error, because a list (even a null list) cannot be compared with a string:

x = $LISTBUILD("")
PRINT $LISTSAME("abc",x)
PRINT $LISTSAME(x,"abc")