Skip to main content

This is documentation for Caché & Ensemble.

For information on converting to InterSystems IRISOpens in a new window, see the InterSystems IRIS Migration Guide and Migrating to InterSystems IRIS, both available on the WRC Distributions pageOpens in a new window (login required).


Compares two lists and returns a boolean value.




list1 An expression that evaluates to a valid list. A Caché list must be created using ListBuild or ListFromString, or extracted from another list using List. The null string ("") is also treated as a valid list.
list2 An expression that evaluates to a valid list. A Caché list must be created using ListBuild or ListFromString, or extracted from another list using List. The null string ("") is also treated as a valid list.


ListSame compares the contents of two lists and returns 1 if the lists are identical. If the lists are not identical, ListSame returns 0. ListSame compares list elements using their string representations. ListSame comparisons are case-sensitive.

ListSame compares the two lists element-by-element in left-to-right order. Therefore ListSame returns a value of 0 when it encounters the first non-identical pair of list elements; it does not check subsequent items to determine if they are valid list elements. If a ListSame comparison encounters an invalid item, it issues a <LIST> error.


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

x = ListBuild("Red","Blue","Green")
y = ListBuild("Red","Blue","Green")
 PrintLn ListSame(x,y)
Copy code to clipboard

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

 x = ListBuild("Red","Blue","Yellow")
 y = ListBuild("Red","Yellow","Blue")
 PrintLn ListSame(x,y)
Copy code to clipboard

Identical Lists

ListSame considers two lists to be identical if the string representations of the two lists are identical.

When comparing a numeric list element and a string list element, the string list element must represent the numeric in canonical form; this is because Caché always reduces numerics to canonical form before performing a comparison. In the following example, ListSame compares a string and a numeric. The first three ListSame functions return 1 (identical); the fourth ListSame function returns 0 (not identical) because the string representation is not in canonical form:

PrintLn ListSame(ListBuild("365"),ListBuild(365))
PrintLn ListSame(ListBuild("365"),ListBuild(365.0))
PrintLn ListSame(ListBuild("365.5"),ListBuild(365.5))
PrintLn ListSame(ListBuild("365.0"),ListBuild(365.0))
Copy code to clipboard

ListSame comparison 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 Then
      PrintLn "Equal sign: number/numeric string identical"
      PrintLn "Equal sign: number/numeric string differ"
   End If
   If 1=ListSame(x,y) Then
      PrintLn "ListSame: number/numeric string identical"
      PrintLn "ListSame: number/numeric string differ"
   End If 
Copy code to clipboard

The equality (=) 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")
 PrintLn ListSame(x,y)," lists are identical"
Copy code to clipboard

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:

 PrintLn ListSame(ListBuild(""),ListBuild(""))," null lists"
 PrintLn ListSame("","")," null strings"
 PrintLn ListSame(ListBuild(""),"")," null list and null string"
Copy code to clipboard

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 (values not identical). 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:

 PrintLn ListSame("","abc")
 PrintLn ListSame("abc","")
Copy code to clipboard

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

 x = ListBuild("")
 PrintLn ListSame("abc",x)
 PrintLn ListSame(x,"abc")
Copy code to clipboard

Comparing “Empty” Lists

ListValid considers all of the following as valid lists:

PrintLn ListValid("")
PrintLn ListValid(ListBuild())
PrintLn ListValid(ListBuild(NULL))
PrintLn ListValid(ListBuild(""))
PrintLn ListValid(ListBuild(Chr(0)))
PrintLn ListValid(ListBuild(,))
Copy code to clipboard

ListSame considers only the following pairs as identical:

PrintLn ListSame(ListBuild(),ListBuild(NULL))
PrintLn ListSame(ListBuild(,),ListBuild(NULL,NULL))
PrintLn ListSame(ListBuild(,),ListBuild() & ListBuild())
Copy code to clipboard

Empty Elements

A ListBuild can create empty elements by including extra commas between elements or appending one or more commas to either end of the element list. ListSame is aware of empty elements, and does not treat them as equivalent to null string elements.

The following ListSame examples all return 0 (not identical):

PrintLn ListSame(ListBuild(365,,367),ListBuild(365,367))
PrintLn ListSame(ListBuild(365,366,),ListBuild(365,366))
PrintLn ListSame(ListBuild(365,366,,),ListBuild(365,366,))
PrintLn ListSame(ListBuild(365,,367),ListBuild(365,"",367)) 
Copy code to clipboard

Nested and Concatenated Lists

ListSame does not support nested lists. It cannot compare two lists that contain lists, even if their contents are identical.

 x = ListBuild("365")
 y = ListBuild(365)
 PrintLn ListSame(x,y)," lists identical"
 PrintLn ListSame(ListBuild(x),ListBuild(y))," nested lists not identical"
Copy code to clipboard

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

 PrintLn ListSame(x,y)," nested list"
 PrintLn ListSame(x,z)," null string is list item"
Copy code to clipboard

ListSame does support concatenated lists. The following example returns 1, because the lists are considered identical:

 y=ListBuild("Apple","Pear") & ListBuild("Walnut","Pecan")
 PrintLn ListSame(x,y)," concatenated list"
Copy code to clipboard

See Also

FeedbackOpens in a new window